[Publication] Add localization-ready layered page composition and locale render targets #406

Sixth implementation checkpoint — PR #454 merged

PR #454 is merged at 0427749a2cccececae2d69aa9fa0a02779603509. #406 remains open; the original acceptance checklist and all prior checkpoint history are preserved below.

New in source:

• Ordinary renderflow/v2 build admission for one local composition source, a format-only target list and a new output bundle. All declared locales are selected by default; locale/raster/PDF/cache settings are optional. Config-relative source/output/cache paths use the existing native boundaries.
• A small shared ResolvedBuild facade for CLI and SDK, dispatching to the existing graph or native composition executor. No second renderer, artificial format or dummy DAG. Native output parsing and policy types are reused.
• Frozen resolved input/config execution; explicit target overrides; partial branch failure and cancellation; read-only planning/dry-run/pre-run cancellation. Generic resume/watch, graph-only controls and unsupported policies fail with actionable guidance.
• Exact common build-plan.json bytes and a last-written renderflow-run.json, alongside unchanged native evidence contracts. Effective config, native plan and artifact-forest identity are bound together; native artifact identities, publication indices and portable locators are retained.
• CLI reports planned/actual output paths consistently, SDK build inventory provides its resolved absolute root, and Ctrl-C reaches composition execution. Explicit caches inside the output bundle are refused.
• Updated schema, help, examples, guide, roadmap and handoff; 11 integration regressions plus 7 spec regressions authored but unrun. No dependency or Cargo changes.

Drift and usability review: independent source review aligned CLI/SDK planning, output paths, cancellation, watch rejection, cache placement and path admission. The normal build path reuses established engines and data types. This is a source-level assessment, not proof of runtime or whole-repository compatibility.

SDK migration: Engine::resolve_execution now returns ResolvedBuild, and execute_resolved consumes it. Callers with explicit ResolvedExecution annotations must migrate. Existing graph planning APIs remain available; graph-only access through the facade is explicit.

Qualification: independent source review and exact local/remote Git blob/tree identity only. Tests, compiler/build, lint/formatting, schema validators, rendering/asset decoding, CLI/native execution, dependency installs/downloads, Cargo resolution and CI remain deferred. No Actions were dispatched or polled. Runtime/visual qualification remains false. Receipt correlation does not authenticate receipts or verify downstream payload bytes.

Remaining boundaries:

1. Broader typography and justified native interchange remain within [Publication] Add localization-ready layered page composition and locale render targets #406; additional print features need concrete consumer requirements.
2. Deferred schema, runtime, visual, platform, release and consumer qualification remains required. The broader [Publication] Add localization-ready layered page composition and locale render targets #406 scope does not block the bounded default-locale ordered-page release.
3. Flow still has no Renderflow adapter. Flow #52 owns it and must consume a qualified, pinned immutable release from [Release] Publish the first verified Renderflow integration-candidate release and reconcile distribution truth #419, preserving exact output selection and partial-run semantics.
4. For the next implementation pass, review [Artifact Forest 9/9] Prove the multi-family artifact forest and hand it to Flow #430's remaining conversion/integration work; keep the later testing and release sweep explicit.

See planner integration decision, handoff, user guide, and minimal build config.

Historical fifth checkpoint — PR #453 merged

PR #453 is merged at e9f5c10f084731cabcb5d623aed488bb04779c4a. #406 remains open; the original acceptance checklist and all prior checkpoint history are preserved below.

New in source:

• Frozen composition planning/execution entry points in the shared planning module and SDK. The common execution plan/artifact forest preserves separate locale/output identities; private captured inputs and measured glyph geometry stay bound to the resolved execution.
• Lazy transcript/SVG preparation shared across terminal cache misses within one locale, with actual stage digests, consumers and reuse counts. Cache hits do not claim rendering. Intermediates are ephemeral; no persistent intermediate cache or cross-locale reuse is claimed.
• Common execution-plan.json and run-manifest.json alongside native receipts. Exact artifact IDs, publication record indices, locators, native metadata and qualification limits are correlated. Partial, failed and cancelled branches remain visible.
• V5 native profile/plan/run/cache/artifact evidence and output-relevant target identities. Canonical v1 inputs and historical schemas are preserved. composition plan now emits a versioned wrapper with native fields under composition.
• Authored unrun regressions, two schemas, updated CLI help, examples, user guide, roadmap and handoff. No dependency or Cargo changes.

Qualification: independent source review and exact local/remote Git blob/tree identity only. Tests, compiler/build, lint/formatting, schema validators, rendering/asset decoding, CLI/native execution, dependency installs/downloads, Cargo resolution and CI remain deferred. No Actions were dispatched or polled. Runtime/visual qualification remains false. Receipt correlation does not authenticate receipts or verify downstream payload bytes; consumers must check bytes and paths.

Integration boundary: the common format graph is a projection; authoritative locale identity lives in the composition stages and artifact forest. Ordinary renderflow/v2 build admission is still pending. Flow currently has no Renderflow adapter, and this checkpoint does not add one. Its future Flow-owned adapter must consume a qualified, pinned immutable Renderflow release and preserve exact output selection and partial-run semantics.

Next:

1. Admit composition packages through the ordinary renderflow/v2 build configuration.
2. Implement the Flow-owned adapter with its qualified immutable-release prerequisite explicit.
3. Broader typography and justified native interchange; additional print behavior against concrete consumer requirements.
4. Deferred schema, runtime, visual, platform, release and consumer qualification, including [Release] Publish the first verified Renderflow integration-candidate release and reconcile distribution truth #419 release evidence.

See planner integration decision, Flow artifact-forest contract, handoff, and user guide.

Historical fourth checkpoint — PR #452 merged

PR #452 is merged at 024b06f83eebeeb2fbe2a6f9106936e77736a3f9. #406 remains open; the original acceptance checklist and all prior checkpoint history are preserved below.

New in source:

• Opt-in, single-page PDF per locale from the same measured SVG and bounded opaque raster path, using the existing lopdf 0.45.0 dependency. No new dependency or external executable.
• Independent PDF DPI, opaque background, binding side, color policy and conformance settings. Defaults are 300 DPI, white, no binding side, assumed sRGB without profile conversion and conformance none. Invalid PDF settings block PDF branches only.
• Explicit full-canvas MediaBox/CropBox, asymmetric TrimBox/BleedBox, safe-area evidence and uniform DPI placement with fractional-pixel overhang clipped to the canvas. Nonzero gutters require left/right intent and already sufficient authored safe-area clearance; no automatic artwork movement.
• Flattened raw RGB image output, bounded to 48 MiB of pixel data and 64 MiB total PDF. Canonical inputs/transcripts retain text and editing; the PDF does not provide selectable text, embedded fonts, layers, tags, ICC conversion, output intents, PDF/X or printer acceptance.
• V4 plan/run/cache/artifact evidence. Fresh and cached PDF admission compares the exact current-writer envelope around a fixed-size RGB payload without parsing arbitrary cached PDF syntax. Artifact hashes separately commit pixel bytes; this is not independent PDF conformance or source-to-pixel proof.
• Authored unrun regression sources, v4 evidence schema, PDF fixture commands and updated provider decision, guide, roadmap and handoff. Canonical v1 inputs and historical schemas remain unchanged.

Qualification: independent source review and remote Git identity checks only. The coding workspace was unavailable, so this checkpoint was authored through the repository connection. Tests, compiler/build, lint/formatting, schema validators, asset decoding, visual/render/CLI/native execution, dependency installs/downloads, Cargo resolution and CI remain deferred. No Actions were dispatched or polled. Earlier registry-authored lock additions still need the later Cargo gate. Runtime/visual qualification remains false; bounded buffers are not total-process RSS or wall-clock isolation.

Next:

1. Locale/output identity integration with the general build planner, artifact forest and Flow consumption, including actual shared-intermediate behavior.
2. Broader typography and justified native interchange with explicit capability/loss boundaries.
3. Additional print features only against concrete consumer requirements, including color management, conformance or book assembly.
4. Deferred schema, runtime, visual, platform, release and consumer qualification.

See PDF provider decision, handoff, and user guide.

Historical third checkpoint — PR #451 merged

PR #451 is merged at c605436445aa26b9b5d496e37cd6a6805f44999f. #406 remains open; the original acceptance checklist and prior checkpoint history are preserved below.

New in source:

• Opt-in PNG per locale from the same measured glyph outlines, artwork, clipping, opacity and layer geometry as SVG. Pinned Resvg/Usvg 0.48.1, Tiny Skia 0.12.0, PNG 0.18.1, Zune JPEG 0.5.15 and SVGTypes 0.16.1.
• Explicit DPI (36–600, default 144) and transparent/opaque-hex background settings; uniform physical scaling, ceil canvas dimensions, straight-alpha RGBA8, sRGB and rounded physical-density metadata.
• Closed captured-resource resolution, bounded complete PNG/JPEG decoding, strict SVG geometry admission and conservative intermediate pixel-surface budgets. Unsupported color profiles, orientation metadata, animation and effects fail explicitly.
• V3 plan/run/cache/artifact evidence; effective raster settings affect PNG branch identity only. Fresh and cached PNG candidates must match the planned decoded dimensions, sample format and metadata.
• Mixed-asset English/German fixture with retained font/license/provenance, authored unrun regressions, new evidence schema and updated guide, roadmap and handoff.

Qualification: source review and Git identity checks only. Tests, compiler/build, lint/formatting, schema validators, asset decoding, visual/render/CLI/native execution, dependency installs/downloads, Cargo resolution and CI remain deferred. No Actions were dispatched or polled. The registry-authored lock graph still needs the later Cargo gate. The assumed-sRGB preview profile does not establish ICC conversion, print acceptance, pixel fidelity or cross-platform repeatability. Surface estimates are not total-process-memory or wall-clock isolation; synchronous rendering is not internally cancellable.

Next:

1. Composed print PDF with explicit color/profile, trim/bleed and binding-side gutter intent.
2. Locale/output integration with the general artifact planner/forest and Flow contracts.
3. Broader typography and justified native interchange, with explicit capability/loss limits.
4. Deferred local schema, runtime, visual, platform, release and consumer qualification.

See raster provider decision, handoff, and user guide.

Historical second checkpoint — PR #450 merged

PR #450 is merged at 3fcff775e43e4126a422391a65b31df0096675c8. #406 remains open; the original acceptance checklist is preserved below.

New in source:

• Pinned HarfRust 0.14.0 and Skrifa 0.48.0 shaping and unhinted outlines from captured static TTF/OTF bytes, with a deliberately bounded Latin LTR horizontal profile.
• Actual nominal/shaped glyph checks, whole-layer declared fallback, UTF-8 cluster and advance/position evidence, authored-line layout and conservative outline/advance overflow diagnostics. No automatic wrapping or shrinking.
• SVG/HTML serialize the exact measured glyph paths. Editable copy remains in the canonical composition/content package and semantic transcripts. Outlined preview lettering explicitly loses native SVG text-object editability.
• V2 profile, plan/run and cache evidence commit provider/report identity; selected-font evidence is authoritative per typography layer. Original v1 schemas remain available.
• Real unmodified DejaVu Sans fixture with retained license/provenance, source-only regression additions and updated provider decision, guide, roadmap and handoff.
• Bounded font parsing, outline memory, fallback attempts, per-locale and aggregate request work. Unsupported webfonts, collections, variable/color fonts, scripts and writing modes remain explicit.

Qualification: independent source review only. Exact upstream release APIs and registry metadata were read; source review fixed coordinate-decimal/measurement parity and font-hash casing. Authored fixture hashes and Git blob/tree identity were checked. Tests, compiler/build, lint/formatting, schemas, native/visual/CLI execution, dependency downloads/installers, Cargo resolution and CI remain deferred; no Actions were dispatched or polled. Metadata-authored lock additions still need the later Cargo gate. Conservative control-point bounds may overestimate actual curve ink; no visual, print or runtime qualification is claimed.

Next:

1. Composited PNG output from the same measured page representation.
2. Print PDF with explicit color/profile, trim/bleed and binding-side gutter intent.
3. Locale/output integration with the general artifact planner/forest and Flow contracts.
4. Broader typography and justified native interchange, with explicit capability/loss limits.
5. Deferred local schema, runtime, visual, platform, release and consumer qualification.

See provider decision, handoff, and user guide.

Historical first checkpoint — PR #449 merged

PR #449 is merged at 8f60d6f4398232f6956091012f533eb2908dfd35. This is the first bounded implementation checkpoint; #406 remains open and the original acceptance checklist below is unchanged.

Implemented in source:

• Versioned native page-composition and separate locale-content contracts, immutable bounded input snapshots, source provenance, layout overrides, reading order, safe-area/clipping diagnostics and captured font-registry resolution.
• Shared SDK and composition inspect/plan/render CLI with exact, subset and all_declared locale selection. SVG, self-contained HTML and JSON/text transcripts have authored serialization paths; unsupported output targets remain visible.
• Per-branch plans and publication receipts, digest-addressed captured inputs, parent/child artifact evidence and verified derivative cache records. General format-keyed DAG/ArtifactForest integration is still pending; current fan-out is scoped to the composition API.
• Primary-source format/tool evaluation, three JSON schemas, a legally reusable synthetic two-panel structural fixture, authored unrun regression sources, user guide, roadmap and detailed handoff.

Qualification: source-reviewed only. Fixture hashes and exact Git publication identity were checked. Tests, compilation/build, lint/formatting, schema validation, native/visual execution, CLI runs, downloads/installers and CI remain deferred by user request; no Actions were dispatched or polled. The bundled 45-byte font is a signature-only structural stub, not a usable typeface. Deterministic serialization is implemented, but actual visual fidelity, glyph coverage, shaping, ink/overflow behavior and runtime compatibility are not yet proven. Every publication candidate still requires human review.

Next implementation order:

1. Add a pinned shaping/raster provider, real licensed font fixtures and measured glyph/fallback/line/ink diagnostics.
2. Add composited PNG and qualified print PDF with explicit color/profile and gutter intent.
3. Integrate locale/output branches with the general build planner, artifact forest and Flow-facing contracts; prove shared intermediate behavior.
4. Add only justified native interchange adapters and richer layer features, with explicit loss and round-trip limits.
5. Run the deferred schema, runtime, visual, platform, release and consumer qualification when authorized.

See handoff, format evaluation and user guide.

Consumer epic: incomprisllc/comics#78
Related to: #338, #367, #373, #380, #387, #396, #400

Outcome

Add a reusable, localization-ready page-composition capability to Renderflow so comics, magazines, posters, and other designed publications can preserve artwork and layout once, substitute reviewed locale content, and deterministically render every declared language/output branch.

The implementation must not pretend that a flattened raster page can be losslessly converted back into its original layers.

Ownership boundary

Renderflow owns the generic artifact types, capability model, planning, composition, adapters, validation, provenance, caching, and locale/output fan-out.

Consumer repositories own their canonical copy, translations, art, layout decisions, language policy, rights, accessibility records, review state, and publication approval.

Flow owns cross-holon orchestration and resumable suite-level workflow state.

Phase 1 — layered-format and tool evaluation

Evaluate existing open-source libraries and command-line tools before building format-specific logic. Compare at least:

• SVG or another open vector/layout representation
• OpenRaster (.ora)
• PSD/PSB interoperability
• layered TIFF or PDF where capabilities are real
• IDML or another publishing interchange format where justified
• a Renderflow-native manifest plus referenced immutable assets

For every candidate, record separately whether Renderflow can detect, inspect, extract, generate, validate, and round-trip it. Include:

• text editability and typography fidelity
• vector/raster layer preservation
• masks, transparency, clipping, and blend modes
• reading order and semantic identifiers
• color/profile and print behavior
• font embedding/references and licensing implications
• cross-platform availability
• deterministic output
• tool licensing and maintenance health
• known loss and unsupported features

PSD may be a useful compatibility output, but it must not become the canonical representation merely because Photoshop is familiar. Select the canonical representation from evidence.

Canonical page-composition artifact

Define a versioned model capable of representing:

• physical page dimensions plus normalized coordinates
• immutable source artwork references and digests
• textless background/art plates
• ordered raster and vector layers
• balloons, caption boxes, masks, shapes, and safe regions
• text containers with stable semantic content IDs
• typography roles, alignment, line-height, padding, and minimum readable size
• reading order and accessibility relationships
• locale-neutral layout plus explicit locale overrides
• source/default locale and declared locale set
• text direction and writing-mode capabilities
• trim, bleed, gutter, and safe-area intent
• provenance, loss profile, approvals, and validation state

Keep content values separable from layout so changing a translation does not require copying or editing the artwork.

Flattened-source policy

• Detect when the source is a flattened raster and report that editable layers are unavailable.
• Never label OCR, segmentation, inpainting, or reconstruction as lossless recovery.
• Permit optional AI-assisted text removal or layer suggestion only through an explicit provider/capability with source/result provenance.
• Preserve the original artifact and emit reconstructed plates as new review candidates.
• Support a human-authored one-time composition package for legacy pages.
• Do not allow reconstructed material to inherit creative approval automatically.

Locale planning and rendering

• Accept exact, subset, and all_declared locale selectors.
• Treat the source/default locale as an ordinary branch through the same planner.
• Expand the artifact DAG across both locale and requested output targets while sharing locale-neutral intermediates.
• Resolve locale-compatible fonts through the existing font registry.
• Diagnose missing glyphs, fallback changes, overflow, clipping, unsafe line breaks, unreadable shrinkage, and unsupported writing modes.
• Permit bounded locale-specific layout overrides with explicit provenance.
• Generate composited raster, print, web, preview, and supported layered interchange outputs.
• Preserve stable relationships between visual output, text elements, transcript/accessibility data, and source metadata.
• Keep unavailable optional outputs observable rather than fabricating them.

Validation and evidence

Every output branch should record:

• source artifact and composition-manifest digests
• locale/content revision
• chosen fonts and fallback decisions
• Renderflow/profile/tool/provider versions
• transform path and effective configuration
• deterministic versus AI-assisted steps
• loss/fidelity declarations
• validation results and human-review requirements
• cache identity and parent/child artifact relationships

Provide machine-readable diagnostics that downstream consumers and Flow can aggregate without parsing human logs.

Tests and fixtures

• Add a small legally reusable multi-panel page fixture with a textless plate and editable text containers.
• Cover source/default plus at least one expanded-text locale.
• Include right-to-left or vertical-writing capability fixtures even if initially expected to report unsupported.
• Test missing glyphs, overflow, stale content, unsafe geometry, flattened-source recovery claims, and unavailable tools.
• Prove deterministic locale fan-out and shared-intermediate caching.
• Add round-trip tests only for properties the selected format contract actually promises.
• Keep ordinary CI independent of proprietary software and remote AI.

Acceptance criteria

• Renderflow has one versioned, format-neutral page-composition contract.
• Consumer text can be replaced by stable content ID without editing source artwork.
• The source/default language and every declared locale use the same planner and renderer.
• Locale/output branches are deterministic, provenance-complete, cacheable, and independently validated.
• Layout, typography, and writing-mode failures are actionable.
• PSD/PSB, SVG, OpenRaster, and other evaluated formats advertise only proven capabilities.
• A flattened PNG is never represented as automatically or losslessly restored to layers.
• Existing document/image publication behavior remains compatible.
• Renderflow does not own or approve consumer translations, creative content, or publication.

Non-goals

• Translating Ego Hygiene or any other publication.
• Rewriting or approving comic artwork.
• Embedding a single consumer's page grammar in Renderflow core.
• Requiring Photoshop or another proprietary application for the canonical path.
• Moving cross-holon orchestration from Flow into Renderflow.

Audit-to-roadmap reconciliation — 2026-10-21

Audit: https://github.com/egohygiene/renderflow/blob/audit/flow-suite-20261021T025401Z/audits/flow-suite-20261021T025401Z.md · Complete roadmap: #367

Six implementation checkpoints merged; ordinary build admission authored, broad typography/native interchange and all visual/runtime acceptance remain open.

Bounded preparation: Review bounded consumer requirements; prepare source-only typography/interchange changes if justified.

Full outcome remains gated (*): Deferred compiler/schema/asset/visual/platform/release/consumer qualification; no need to block ordered-page initial candidate.

The maintainer's implementation-sprint qualification deferral remains in force. This audit ran no Renderflow tests, compiler/build/Cargo resolution, product lint/format/schema qualification, native/CLI/provider/visual execution, installers or new CI. Reading existing exact-source provider records is not a qualification rerun. Source implementation and authored tests are not passing-test, native-fidelity, release or downstream-consumer evidence.

This is an additive planning note. The full original issue, acceptance criteria, scope, parent references and historical checkpoints remain authoritative and unchanged. No acceptance box or issue is closed by this audit. Recommended ledger parent: #367.