qbit-document-generation/docs/AUTHORING.md

Source authoring and retained previews

Use Edit output filename on a template to set a basename without .pdf or .zpl; the format supplies the extension. New templates start with document. Blank naming fields preserve generated-revision-<id>. Publish the edited draft separately to affect future requests.

For record-specific names, select a published context script first, then set the optional top-level result key, for example outputName. The script can return { outputName: 'Packing slip ' + order.number }. The host reads that exact property as data; dotted paths, expressions and reserved record are refused. Missing, non-string or unsafe values fail generation without fallback. Clear the key before clearing its script.

Basenames are limited to 180 UTF-8 bytes. Path separators, control/format characters, reserved device names, PDF/ZPL extensions, trailing dots and surrounding whitespace are refused rather than altered. The resolved name is committed before rendering and reused by retained storage, download results and reprints. Completed retries do not rerun the script. Source, asset and context edits preserve the policy under their optimistic draft lock.

Existing installations must apply foundation/src/main/resources/db/migrations/20261031-output-filenames-h2.sql or 20261031-output-filenames-mysql.sql once before running this version. Bootstrap does not alter existing tables. Nullable additions preserve historical rows and queued revision hashes; retained originals are not renamed. Staged provider verification is tracked in SESSION-STATE.md.

The QBit adds a Document Generation workspace using standard QQQ tables and processes. Configure explicit source tables with withSourceTables(...) to expose record generation and bounded batch actions. The workspace creates document types, physical stock sizes, table bindings and templates. Stock dimensions and margins are integer micrometres; output resolution is explicit DPI.

Select a template and use Edit template source. PDF source uses the existing HTML code editor and FreeMarker HTML/CSS syntax; ZPL source uses the JSON editor and the renderer's restricted scene schema. These are separate source documents sharing the same pinned context script and assets. This is a source editor, not a visual layout designer or arbitrary raw ZPL terminal.

Use Rename on a document type, stock size or template to change only its display name. The form loads the current name; the saved name is trimmed, must be nonblank, at most 200 characters and free of control characters. Identity, stock geometry, bindings, drafts, published revisions and queued pins are untouched, and ordinary table editing of these rows stays denied. The action requires document-generation.configure at discovery and again at save, and the native update keeps the host's configured field-level audit.

Use Select or clear published context script to attach a context-tested immutable script publication. Search by project name in the ordinary QQQ selector. The optional scripting adapter checks current project/execute permissions and successful context testing of the exact published build, then obtains its artifact/hash pin server-side. No internal reference needs to be typed or copied from the IDE. Selection changes only the draft; publish the template explicitly. A newer script publication never changes an existing template or queued revision. Clearing requires the explicit checkbox, and source editing preserves the current selection even if a client submits a forged internal pin. Discovery is intentionally bounded; narrow the project search when necessary.

An edit captures the current draft fingerprint. Saving under a row lock compares the original fingerprint, so stale editors receive an error rather than overwriting another save. Publication performs isolated validation, then locks and compares the draft again before atomically inserting its immutable revision and changing the active revision. If validation overlapped a draft edit, publication refuses the changed draft. The unversioned three-argument Java saveDraft remains an explicit overwrite API for trusted integrations; native source forms use saveSources with the fingerprint and preserve their owner-resolved context pin.

Select retained asset for draft searches a bounded native selector of currently authorized, released PNG/JPEG/TrueType versions. The owner resolves hash, media type and length; users do not enter them. Choosing a version and name atomically adds the immutable asset and includes it in the draft under the captured optimistic fingerprint. Install the optional Record Files RetainedAssetSelection through withAssetSelection(...); an absent provider refuses selection. The renderer independently reauthorizes and reads the exact version at validation/render time. Metadata selection never grants file access.

Remove included draft asset and Replace included draft asset select readable names from the current template's bounded asset list. Removal changes only draft membership. Replacement resolves a fresh authorized retained version, creates a new immutable reference and preserves the source alias, font family/weight/style and manifest position. Images can replace images, and TrueType fonts can replace TrueType fonts; switching roles is refused. Previously published/queued revisions and retained originals remain unchanged. A stale form, another template's asset, or an already removed/replaced reference is rejected.

Source editing displays the included names and preserves their manifest; submitted internal asset-ID text is ignored. There is no manual ID assembly. Resources are addressed by name in source, so image/table/layout order belongs to the template rather than an asset-list reorder control. Removing an asset does not rewrite source: update any source reference before validation/publication. Empty drafts get a clear message when remove/replace is requested. Native per-request enum metadata supplies choices without mutating the installed process definition or adding custom frontend code.

TrueType assets expose CSS family, integer weight100–900 and normal/italic style. Older four-field font references keep their name as family and400/normal defaults, including the canonical hash of already queued revisions. Explicit nondefault faces participate in that hash. Images cannot carry font attributes. Existing databases need the additive nullable font columns; db/h2/002_asset_font_faces.sql is an H2 upgrade, not a MySQL deployment migration. Published revisions pin asset identities, script identity, sources, stock and margins.

Generate retained draft preview accepts one source record identity and PDF/ZPL selection. It creates an immutable PREVIEW revision, executes the ordinary source authorization, isolated rendering, strict audit and Record Files intake workflow, and leaves the active published revision unchanged. The preview has a normal generation request and retained attachment. Retrying its process request key returns the same request; it does not regenerate bytes. Quarantine rules still apply. Results expose native request/file links and, when an authorized download provider is installed and release completed, explicit preview/download actions. Authenticated delivery uses verified response bytes and a durable completion receipt; its URL is never rendered as an ordinary browser link or iframe. PDF display uses the shared canvas preview component. The resulting preview remains a retained, audited file.

Barcode catalog and template examples displays the optional renderer's bounded packaged catalog plus editable FreeMarker HTML and restricted ZPL JSON examples. The renderer owns the catalog and its supported options; the foundation copies no encoder registry and does not evaluate source to display help. An unavailable catalog provider fails explicitly. Renderer version qualification and physical barcode acceptance remain separate.

Native result fields use generic LINK, FILE_DOWNLOAD, FILE_PREVIEW and CODE_EDITOR adornments. Links target current QQQ table/record metadata. Authenticated versus signed delivery is explicit; missing/unknown delivery metadata cannot downgrade into a direct link. JSON result fields remain for compatible integrations.

Validate and publish draft creates a PUBLISHED revision. Generation actions select a published template. Existing queued items retain their original revision even after another publication. Existing previews and output versions remain independently retained and auditable.

The source selector is populated when host source tables are configured. Otherwise the form accepts a table name validated by the definition service. Defining a binding requires configuration authority; actual generation still requires the current source record permissions. The native app currently has the fixed name documentGeneration; duplicate registration is rejected.

Verification: full113 foundation tests and178 focused frontend tests passed; optional bridges renderer23/scripting3/retained16 passed against the final artifacts. Context selection adds native process/PVS tests without frontend-specific source changes. Real MySQL/H2 coverage includes exactly one successful simultaneous draft editor. The frontend production build and five real Chromium PDF/order/tracked-delivery checks passed. These tests use trusted renderer/intake fixtures; they do not qualify hostile-template containment, complete host workflow usability or physical output.