Documentation index

This page is generated from docs/catalog.json and document frontmatter. The site describes a pre-standard research project.

• Source digest: sha256:d554926f107ca96300cd2ac76757a15e9c9cbdc7ced95047e6d1f380ebc3712c
• Published Markdown files: 266
• Navigation sections: 10

Status inventory

NUIF authored-interface interchange research manuscript

Architecture, executable profiles, resource packaging, reconstruction research and open risks

Refpath contributors
Version working-2026-08-31 · 2026-08-31

Manuscript status: working technical manuscript; not peer reviewed. This generated document does not change the status of any included specification module.

Abstract

This manuscript evaluates a layered authored-interface interchange model through prior-art synthesis, bounded adapter profiles and executable conformance experiments. It also separates proposed resource packaging, source-backed capture and screenshot reconstruction from the narrower implemented alpha evidence. It records the architectural hypothesis, implemented evidence, unresolved risks and governance conditions without claiming specification stability, reconstruction accuracy or universal format coverage.

Reproducibility

The body is compiled from 13 canonical whitepaper modules at source digest sha256:d554926f107ca96300cd2ac76757a15e9c9cbdc7ced95047e6d1f380ebc3712c. Editorial changes belong in those source modules.

NUIF foundation

NUIF investigates a portable, vendor-neutral draft specification for authored user-interface documents. The candidate model is intended to preserve meaning across editors and implementation targets rather than treating a rendered bitmap, a vendor scene graph, or source-language AST as the universal truth.

Thesis

A useful portable interface specification must coordinate several representations instead of collapsing them into one:

1. semantic/document containment;
2. component and instance identity;
3. authored layout and responsive constraints;
4. resolved geometry at explicit evaluation contexts;
5. geometry, paint, typography, and assets;
6. design-token references and themes;
7. interaction/state and data-binding graphs;
8. source/tool provenance and correspondence;
9. extension payloads that can survive unknown intermediaries;
10. deterministic operations, diff, patch, and reconciliation.

Portable resources add a second identity boundary: editable semantic assets retain stable IDs, while exact image/font bytes use immutable content digests. Package paths and source URLs are locators/provenance, not identity.

NUIF therefore treats portability as a synchronization problem as much as a serialization problem.

Architectural hypothesis

The working model is a small canonical core plus coordinated graphs and extension dialects. The containment tree answers ownership and order. Typed relationship graphs express constraints, components, tokens, interactions, provenance, dependencies, and other relationships that do not belong in a tree.

The reference implementation will preserve both authored and resolved state. Resolved state is always scoped to an evaluation context and is never allowed to silently replace authored intent.

Fidelity model

Every adapter and transformation must classify material mappings:

• lossless — semantics are preserved exactly;
• representable — equivalent target semantics exist, even if encoded differently;
• approximated — a declared approximation is produced;
• preserved_unrenderable — data survives as an extension but the target cannot render/edit it;
• unsupported — data cannot currently be represented or preserved safely.

Silent loss is a conformance failure.

Explicit non-goals

NUIF does not promise to infer the unique original source program from pixels, reproduce arbitrary JavaScript execution, make every platform text renderer bit-identical, or force every target to support every capability. The draft specification should make such boundaries inspectable and machine-readable.

Screenshot reconstruction is therefore an optional inference client, not a new canonical truth. It may propose a validated editable hypothesis and calibrated alternatives, but screenshot-only evidence cannot be classified as lossless authored source.

Reference implementation role

The Rust implementation and editor are executable research instruments and conformance references. They do not define semantics by accident; normative behavior belongs in spec/ and must be testable independently.

Canonical module.

NUIF architecture thesis

NUIF is a specification-first authored-interface model. Its center is neither a vendor editor nor a source framework.

Core thesis

A portable interface document must retain intent, structure, relationships and evaluated results simultaneously. A single flattened scene tree cannot preserve enough information for loss-minimizing round trips across editors and runtime frameworks.

The recommended architecture is a layered hybrid:

Document containment tree
        │ stable IDs
        ├── component / instance graph
        ├── token / theme graph
        ├── layout constraint graph
        ├── interaction / state graph
        ├── provenance / correspondence graph
        └── asset dependency graph

Authored model ──evaluate/lower──► resolved model ──► render scene
      ▲                               │
      └──────── reconcile / lift ◄────┘

Borrowed foundations

• MLIR: dialects, explicit lowering, partial legality and multiple abstraction levels.
• OpenUSD: non-destructive composition, references, layers and variants.
• glTF: small core, extension registry, used/required capabilities.
• DTCG: token interchange.
• SVG/Unicode/OpenType: geometry and text foundations.
• Retentive/symmetric lenses: synchronization with preserved source regions.

New work required

NUIF must define the missing combination: authored UI semantics + resolved state + cross-tool provenance + structural loss accounting + source patch synchronization.

Canonical layers

1. Document layer — identity, containment, semantics, accessibility.
2. Component layer — definitions, instances, slots, parameters, variants and overrides.
3. Layout layer — authored sizing/layout intent independent of resolved geometry.
4. Visual layer — geometry, paint, text and effects.
5. Behavior layer — interactions, states, animation and data bindings.
6. Resolved layer — computed layout, shaped text, flattened paint/effect plans for a declared evaluation context.
7. Provenance layer — source/destination correspondence and fidelity diagnostics.
8. Resource layer — stable semantic assets bound to content-addressed bytes, package/resolver locators and derivation records.

No lower layer is permitted to silently erase a higher-level authored construct. Lowerings that cannot represent a construct must emit fidelity records.

Stable identity

Identity is semantic and independent of path, order and display name. Moving an entity does not change its ID. Content hashes identify immutable resources and canonical snapshots, not editable semantic entities.

Compiler and reconstruction ports

Deterministic source adapters and probabilistic screenshot reconstruction meet at the operation boundary:

retained source + resolved host observations ─┐
                                              ├─> typed operations -> core
pixels + OCR/CV/model hypotheses ─────────────┘                    -> render/evaluate

Source-backed and screenshot-only inputs retain distinct evidence classes. A model/provider is replaceable and cannot redefine the operation grammar, validator, layout semantics, resource identity or fidelity ceilings.

Falsifiability

The architecture fails if the v0 experiment cannot preserve a non-trivial responsive component through editor→HTML→NUIF→editor while retaining component identity, token bindings, layout intent, an opaque foreign extension and a minimal source patch after an edit.

The resource/reconstruction extension fails if independent package writers cannot reproduce the proposed bytes, if browser capture cannot be pinned without secret leakage, if visual objectives reward flat screenshot copies, or if adaptation fails to beat the untuned tool-assisted baseline on a frozen holdout.

Canonical module.

Layout and rendering research synthesis

Layout is not geometry

NUIF separates authored constraints from resolved boxes. Fixed x/y/width/height are valid authored values for freeform content, but they are not the universal layout representation.

The initial layout vocabulary contains families rather than one universal algorithm:

• freeform — transforms/anchors and explicit geometry.
• stack — one-dimensional flow with intrinsic sizing, distribution, alignment and gaps.
• flex — web-compatible flexible layout semantics.
• grid — bounded explicit fixed/fr tracks, spans and deterministic no-implicit-track placement in profile 0; broader CSS Grid features remain capability-reported adapter input.
• constraint — relational linear constraints for editor/native-layout cases.
• custom — extension/dialect-defined evaluator with declared fallback/resolved geometry.

Common sizing primitives are normalized across families: fixed, intrinsic-min, intrinsic-max, fit-content, fill/available, percentage, min/max clamps, aspect ratio and content measurement.

Taffy is the recommended first evaluator for CSS-compatible block/flex/grid behavior because it implements web algorithms in Rust. SwiftUI’s proposal-response model and Cassowary-style constraints demonstrate why the canonical schema must remain a superset rather than serializing Taffy’s Style directly.

Evaluation context

Resolved layout is keyed by an explicit context including viewport/container size, pixel ratio, locale, writing direction, font set, token/theme selection and feature/dialect capabilities. Multiple resolved snapshots may coexist as caches or conformance fixtures.

Rendering semantics

The draft specification defines the visual meaning of paths, fills, strokes, transforms, clipping, masks, gradients, compositing, images, text and supported effects. It does not specify GPU command buffers or a renderer implementation.

The reference renderer uses a backend trait. Vello/wgpu is the leading interactive experiment, but conformance requires deterministic raster comparisons and must permit CPU reference rendering where GPU differences would make tests unstable.

Text

Canonical text remains Unicode text + style runs + semantic annotations + font references. Shaping produces resolved glyph IDs, clusters, advances and offsets using pinned font data and a declared Unicode/shaping version. A glyph cache never replaces semantic text.

Portability reports must distinguish font substitution, missing glyphs, line-break differences and rasterization differences from document-model loss.

Canonical module.

Protocol, portability and synchronization

NUIF treats portability as an ongoing synchronization problem.

Operations

The protocol operates on stable entities and semantic properties. Operations include create/delete/move, set/unset property, list/set relation edits, component/instance overrides, token bindings, extension edits and transactions. Editor gestures lower to these operations.

A drag inside a stack should usually become a reorder or layout-property edit; a drag in freeform space may become a transform edit. GUI coordinates are input data, not the protocol abstraction.

Patch model

A patch is a deterministic ordered set of operations with base snapshot identity, optional preconditions, transaction metadata and provenance. Patches can be replayed headlessly.

Three-way merge uses stable identity first and structural matching only when identity is absent. Conflicts are typed: property, delete/edit, ordering, relationship, extension and semantic-lowering conflicts.

Correspondence

Adapters maintain correspondence records between NUIF entities/properties and foreign constructs such as DOM nodes, CSS declarations, Svelte component props or design-tool node IDs. Correspondence is separable from the canonical design so source-specific metadata can be detached when unnecessary.

Fidelity classes

Every adapter/evaluator may report:

• lossless — semantics preserved and reconstructable.
• representable — equivalent semantics represented through different constructs.
• approximated — visible/behavioral approximation with known semantic loss.
• preserved_unrenderable — data retained opaquely but not understood/rendered.
• unsupported — data could not be safely preserved.

Silent degradation is a conformance failure.

Canonical module.

Serialization, collaboration and governance

Logical model before encoding

NUIF defines one logical model with multiple conforming encodings.

Text form

A canonical, reviewable representation is implemented for examples, fixtures, diffs and Git workflows. nuif-text-0 fixes number formatting, UTF-8 key order, layout and strict decode/canonicalize behavior; later text profiles may evolve only through explicit versioning.

Binary form

Deterministic CBOR is the profile-0 binary form because the NUIF profile closes the choices left by RFC 8949 without coupling the logical model to generated code. The executable codec gate finds it near 41% of canonical-text size at 4,096 entities on an Apple M5 Pro run, while its typed decode path is slower than text. That result supports CBOR as a compact canonical form, not as a universal latency winner.

A candidate is timed only after complete-model round trip, canonical fixpoint and unknown-data preservation through a neighboring edit. Protobuf does not specify canonical binary output. FlatBuffers deliberately permits different byte layouts and old readers ignore new fields, so a rebuilding editor needs a separate retention strategy. Cap’n Proto specifies a schema-agnostic canonical form and is the preferred next experiment, but it still needs a complete NUIF mapping, bounded old-reader edit trial and two agreeing canonical writers. Compiled zero-copy runtime caches remain separate, explicitly noncanonical profiles rather than replacements for authoring interchange.

The experimental package form separates manifest/document records from content-addressed resources. RFC 0010 selects a candidate deterministic ZIP profile with fixed mimetype, canonical manifest/document records and SHA-256-addressed blobs. Bare encodings use explicit .nuif.json and .nuif.cbor names. Exact ZIP header fixtures, two independent local writers and bounded image/font segments now exist. Cross-platform and externally authored writer evidence remains required before package-profile acceptance.

Semantic document, resource and package hashes have different scopes. Stable asset identity is not content addressing. Unknown extension payloads remain explicit typed bytes/values and must not depend on accidental codec unknown- field behavior.

Collaboration

Canonical documents do not require CRDT tombstones, clocks or replica metadata. A collaboration profile maps NUIF operations to an append-only/change structure and can use Automerge, Yjs or another convergent transport. Checkpoints serialize back to canonical NUIF.

This keeps offline files simple and permits multiple collaboration engines.

The executable register profile uses causal multi-value registers. The separate existing-tree profile replays uniquely ordered moves, rejects cycles, models deletion as profile trash and orders siblings through stable RGA-style origins. Semantic move and deletion conflicts remain visible even when the profile can choose a deterministic checkpoint. Automerge is presently tested as an operation-set transport, not claimed as an implementation of the tree algorithm.

Governance

Early development occurs in refpath/nuif, but the architecture assumes eventual neutral stewardship. A plausible progression is:

1. OSS research/reference implementation under Refpath.
2. public RFC process + implementer registry.
3. independent community/working group once two independent implementations exist.
4. investigate W3C Community Group for UI/document semantics and/or Khronos-style governance if renderer/asset vendors become primary stakeholders.

Specification text, schemas and conformance tests need clear royalty-free contribution/IP terms before claiming standards-track stability.

Canonical module.

Prior art and competitive map

No surveyed system currently combines the whole NUIF thesis. Several solve important subsets.

Directly borrow

Stable standards concepts: SVG geometry, DTCG token values, Unicode/OpenType text foundations, CSS-compatible algorithms for matching profiles, glTF-style capability declarations, OpenUSD-style composition principles, MLIR-style dialect/lowering discipline.

Adapt

Retentive lenses → property/source correspondence; CRDTs → collaboration profile; WebRender/Vello/Skia → renderer boundary and conformance strategy; Tree-sitter → source-preserving adapter infrastructure.

Invent/prove

The proposed integration combines authored and resolved UI state, stable cross-tool semantic identity, opaque extension retention, fidelity accounting, bidirectional semantic patches and a native open editor whose internal state is the draft model itself.

Canonical module.

Implementation language and runtime choice

Decision: Rust reference core

Rust is the strongest default for the reference implementation because the project simultaneously requires untrusted binary parsing, graph/document transforms, geometry, text shaping, native/WASM embedding, GPU access, fuzzing and stable C-compatible boundaries.

Alternatives

• C++ has the deepest graphics ecosystem and mature Skia/Yoga integration, but expands memory-safety risk in parsers/plugins and makes a browser/WASM-safe reference core less attractive.
• Zig offers excellent systems control and C interoperability but has a smaller mature graphics/text/schema ecosystem and less API stability for a standards reference implementation.
• Go is strong for services/tooling but weaker for low-level rendering/WASM/native GUI integration and deterministic allocation-sensitive engines.
• TypeScript is ideal at web/editor adapter boundaries but unsuitable as the only renderer/codec/reference-core implementation.

Stack

• Rust: document model, operations, layout abstraction, codec, renderer scene, conformance, WASM bindings.
• Taffy: initial CSS-compatible evaluator behind NUIF types.
• Vello/wgpu: interactive renderer experiment behind a NUIF renderer trait.
• HarfBuzz-compatible shaping: text experiment with pinned font inputs.
• Masonry + AccessKit: reference editor shell (ADR 0006, accepted; toolchain 1.98.0, MSRV 1.96); Svelte 5 + TypeScript for the later browser demonstration over the WASM bindings.
• Tree-sitter/language-native parsers: source adapters where concrete syntax retention is required.

Adapters MAY be written in the ecosystem-native language; conformance is against behavior/protocol, not implementation language.

Canonical module.

Risk register and impossibility boundaries

Fundamental boundaries

1. Rendered output is underdetermined. Pixels/boxes cannot uniquely reveal whether layout came from flex, grid, constraints, absolute positioning or runtime code. Imported foreign content must mark inferred intent.
2. Arbitrary program behavior is not serializable as UI structure. NUIF does not promise to recover arbitrary JavaScript/Swift/Dart application logic.
3. Text is environment-sensitive. Font files, shaping versions, fallback and rasterization can differ. Exact conformance requires pinned inputs; portability must classify substitution separately.
4. Platform-native controls differ. Semantic equivalence may be possible while exact visuals/behavior are platform-specific.
5. Effects/shaders can exceed a portable core. Extensions may be preserved without being renderable.
6. Standard complexity can kill adoption. IFC/STEP demonstrate the cost of excessive semantic scope.
7. A single reference implementation can accidentally become the spec. Independent implementation is a standards gate.
8. Resource bytes carry legal and security constraints. Exact font/image preservation does not imply permission to redistribute or safe decoding.
9. Visual metrics are gameable. A flat screenshot can look exact while discarding editability, semantics, accessibility and responsive behavior.
10. Model confidence can be misleading. Raw probability is not calibrated correctness and cannot upgrade inferred evidence into source truth.
11. Capture can leak secrets. Browser/network/accessibility observations may expose credentials, personal data or proprietary content unless collection, export, retention and training are separately bounded.

Containment strategies

• explicit fidelity reports and inference confidence;
• authored + resolved snapshots instead of pretending either alone is canonical truth;
• opaque extension preservation;
• deterministic capability/evaluation contexts;
• small core + profiles;
• reference implementation backed by normative conformance fixtures;
• fuzzing/resource budgets for all untrusted inputs;
• early independent implementation and adapter experiments.
• stable asset IDs separated from resource digests, locators and provenance;
• verify resource size/digest before decoding and never fetch implicitly;
• typed operation output for models, atomic validation and finite correction loops;
• structural/text/resource/edit-task metrics alongside visual diagnostics;
• calibrated decision-level confidence, alternatives and abstention;
• private captures default to local processing, no retention and no training.

Current implementation risks

• The macOS graphics fork is a maintenance boundary. The editor pins refpath/xilem commit 1b96eb8; its parent eabfe0a moves the active renderer from wgpu 28 and metal-rs to wgpu 29 and the objc2 Metal bindings. The fork changes public API call sites and does not patch the Objective-C blocks ABI. Each fork update requires the editor tests, reverse dependency trace, and macOS Metal window smoke test recorded in nuif:research:macos-metal-block-future-incompatibility. A separate refpath/metal-rs move-to-block2 branch exists only for review; NUIF does not depend on the deprecated binding or that experimental patch.
• Release signing is credential-bound. The editor packaging gate builds, archives and smoke-tests an unsigned host package. Platform signing and notarisation require release credentials and remain separate from source conformance.
• Portable resources are only narrowly implemented. The deterministic package, RGBA8 PNG and static single-face TrueType subsets have executable gates, while CPU profile 0 remains unchanged. RFC 0010 cannot be accepted until broad media/font matrices, the configured Linux/Windows/macOS jobs produce passing hosted evidence, external reproduction, calibrated aggregate budgets and interoperability review pass.
• Capture and reconstruction accuracy remains unestablished. RFC 0011 and specification 14 now have bounded fixed-input contracts, a local pinned browser fixture and a typed synthetic evaluation report. They establish interfaces, refusal rules and metric consistency, not portable browser-capture or screenshot-reconstruction accuracy. No current release makes those accuracy claims.

Thesis falsifiers

The project should rethink its architecture if ordinary source round trips require broad regeneration, if unknown extension preservation cannot survive routine edits, if the layout vocabulary becomes a vendor-property dump, or if a second implementation cannot reproduce v0 behavior from specification + fixtures alone. The resource/reconstruction path should additionally narrow if package bytes cannot reproduce across writers, correction loops improve pixels by deleting semantics, confidence cannot support useful risk/coverage, or tuned models do not beat the untuned tool-assisted baseline.

Canonical module.

Governance and standardization strategy

NUIF starts under Refpath because research and implementation need a concrete home, but the target is neutral stewardship.

Repository governance now

• Public RFCs for semantic changes.
• ADRs for reference-implementation choices.
• Research evidence is distinct from normative requirements.
• Extension registry changes require examples and conformance fixtures.
• No vendor adapter can redefine core semantics.

Standardization path

A W3C Community Group is a plausible early venue for document/component semantics and coordination with Open UI/DTCG, but NUIF should not enter formal standards work before an executable v0 and at least one external implementer exist. Khronos/ASWF-style governance offers useful precedent for graphics/rendering and extension registries. A neutral foundation can become appropriate once multiple vendors/projects depend on the format.

IP/licensing goals

• reference code: permissive dual MIT/Apache-2.0;
• specification/schema/conformance text: permissive terms compatible with standards adoption;
• contributions: explicit patent/IP policy before standards-track claims;
• trademarks/conformance branding: separate from implementation copyright.

The project must not call itself an industry standard merely because the repository is public. Conformance, multiple implementations and neutral governance are prerequisites.

Canonical module.

Naming and project identity

NUIF is the current working name and repository slug, not yet a cleared standards trademark.

A public reconnaissance found prior acronym use in an old Nexus User Input Framework and in a 2024 computer-vision paper, plus unrelated uses. None currently appears to occupy the same open UI-authoring interchange category, but collision risk is non-zero.

The architecture therefore separates human branding from protocol identity. Stable schema namespaces, extension IDs and version identifiers must not depend on a product trademark remaining unchanged.

Before v0.1 branding is promoted outside the research project:

1. perform repository/package/domain/trademark clearance in key jurisdictions;
2. decide whether NUIF is an acronym or simply a proper project name;
3. reserve crate/package/extension namespaces;
4. define conformance-mark governance separately from the open specification;
5. make any rename before third-party persisted documents become common.

Canonical module.

Research coverage and continuous completeness

A research repository cannot truthfully claim to contain every paper that will ever be relevant. NUIF instead defines operational completeness: every planned architectural front must have an explicit status, evidence links, unresolved questions and an experiment/decision path.

research/coverage.yaml is the machine-readable coverage contract. It maps the founding research plan to research IDs, specification modules, RFCs/ADRs, code seams and experiments. The project can therefore identify gaps structurally rather than relying on prose search to infer that a topic was forgotten.

Current state

All founding fronts are represented. The resource, browser-capture, reconstruction-evaluation, adaptation/distillation and AI artifact-governance fronts are now explicit rather than hidden inside “serialization” or “inference.” Decisions that can safely be made from mature prior art are marked covered. Questions whose answer would be premature without an implementation are marked experiment-required. Areas whose evidence base will continuously evolve—prior art, adapters, reconstruction and data/model governance—remain ongoing by design.

This distinction is important: marking an open research problem as finished would be less rigorous than preserving it as a first-class graph node.

Additional boundaries from the final sweep

• WAI-ARIA and accessibility API mappings support a semantic-role/state layer distinct from platform-specific accessibility trees. The bounded nuif-web-accessibility-0 lowering now proves computed role/name/state agreement for one eleven-node fixture across pinned Chromium, Firefox and WebKit while retaining native-platform and behavior non-claims.
• KHR_interactivity provides contemporary precedent for portable, capability-aware behavior graphs rather than arbitrary scripts embedded in visual nodes. The smaller nuif-behavior-state-machine-0 sidecar now has exact Rust/Node traces for ordered guards, state, effects and explicit required/optional capability handling without claiming a final semantic schema. Its first wire experiment is one inert canonical-CBOR, content-addressed package resource: a Rust gate validates document binding and hostile cases while an independent Python ZIP reader checks exact container bytes. The attachment remains outside the canonical Document and never grants execution authority. A separate one-way web lowering maps the bounded effects through native activation, hidden and an ARIA status region; five events agree across pinned Chromium, Firefox and WebKit under one exact CSP-hash-authorized runtime without extending that evidence to native UI or screen-reader speech.
• ReverseORC and related layout-inference work show that multiple viewport observations materially improve recovery of responsive intent.
• Screenshot-to-code research continues to show that visual reconstruction is not equivalent to recovering authored layout or behavior.
• Merkle/content addressing is appropriate for immutable assets and snapshots but not for editable semantic identity.
• EPUB OCF and OCI descriptors support a narrow manifest-driven package with size/digest verification; NUIF now has an in-repository independent-writer fixture. A three-OS CI matrix now exercises the package, image and font gates, while successful hosted evidence and external reproduction remain open.
• OpenType and Fontations evidence now supports one executable static TrueType package baseline with a pinned HarfBuzz metadata oracle. The retired ttf-parser decision remains documented; broad font formats, portability outcomes and shaping/raster integration remain experiment-required. Warmed parser and packaged-validation allocation ceilings cover every accepted fixture.
• Browser source capture and screenshot reconstruction are different evidence lanes and cannot share a blanket lossless claim.
• Current screenshot-to-code work supports OCR/region/hierarchical and render- correction experiments, not a claim that authored UI recovery is solved.
• LoRA, quantized adaptation and distillation are conditional experiment techniques; evaluation, rights-cleared traces and artifact governance precede training.

The continuous-research process should periodically re-run topic searches, append or supersede research records, and update research/coverage.yaml only when new evidence or experiments change the status of a front.

Canonical module.

Cross-industry patterns: evidence, adoption and rejection

This document synthesizes 52 research records added on 2026-08-29 from visual-effects interchange, game-engine asset systems, programming-language research on bidirectional transformation and layout verification, distributed-systems testing, and 2D-rendering conformance practice. Each pattern below is classified as borrowed (adopted as is), adapted (adopted with a stated change) or rejected (ruled out with the reason). Record identifiers (nuif:research:*) carry the locators; this document does not repeat them.

Method

The 52 records synthesized here were reviewed from primary sources (specifications, source code at a named commit and papers with DOI). reviewed does not mean every material claim has completed locator-level verification; research/AUDIT.md defines the stricter verified state. Claims resting on one record inherit its evidence status as well as its confidence. Source conflicts remain explicit until an RFC or experiment resolves them.

Patterns

Document model and composition

Identity and ordering

Unknown data preservation and schema evolution

Operations, undo and merge

Canonical encoding

Layout

Rendering determinism

Text

Testing methodology

Editor automation

Ruled out

The following were examined and excluded from the architecture; the reason is recorded so the question is not reopened without new evidence.

• A self-describing binary struct layout (Blender DNA): solves version drift for one implementation but does not preserve data it cannot re-save and does not compose with a schema-versioned interchange model.
• Memento undo as the canonical history: does not commute, cannot be merged, and bloats logs; inverse operations are required by spec/06.
• Integer child indices in Move and Insert as the only order representation: non-commutative under concurrency; a list identifier is required for the collaboration profile and harmless for the canonical form.
• GPU rendering as a normative oracle: implementation-defined by the WebGPU and WGSL specifications.
• Perceptual UI screenshot tests as the primary editor test: platform-dependent text rendering makes them a shell-wiring check only.
• Heuristic tree matching for NUIF-native merges: unnecessary with stable identity and a source of spurious moves.
• Whole-project regeneration as the synchronization model: contradicted by the lens and delta-lens laws that NUIF’s patch model must satisfy (lenses-foster-boomerang, bidirectional-evaluation-direct-manipulation).

Consequences for the specification

The records imply the following changes. Items 1–3 were decided by follow-up research on 2026-08-29 and are recorded as accepted RFCs; items 4–6 remain proposals.

1. Sibling order is a canonical array without keys; Insert and Move use anchors (Start, After(id)); the collaboration profile maps anchors onto a Fugue-family list CRDT (RFC 0006).
2. nuif-cbor-0 follows deterministic preferred serialization while preserving integer/real data-model identity; real zero is positive floating zero, text and CBOR key orders are distinct, strict decoders reject non-canonical input, text hashes through CBOR and strings remain verbatim (RFCs 0005 and 0008).
3. Entities of unknown kind load as Unknown with typed core fields and an opaque payload; ignorant implementations preserve bytes, knowing ones may re-encode; validation severities follow the glTF pattern (RFC 0007).
4. Every serialized record kind carries a schema version; migrations are registered pure functions; newer-than-known versions load as Unknown for entities (RFC 0007) and are diagnosed for other records.
5. Validation, import and export reports follow one schema with stable codes, severities and pointers.
6. Layout conformance declares tolerance tiers per case and classifies every divergence from a browser reference as schema loss, evaluator defect or implementation-defined behavior.

Open questions raised by this synthesis

Recorded in research/questions.yaml: cbor-float-zero (decided, RFC 0005), sibling-order-identifier (decided, RFC 0006), unknown-kind-preservation (decided, RFC 0007), editor-toolchain-msrv (ADR 0006), layout-assertion-vocabulary, render-tolerance-tiers.

Canonical module.

Resources, capture and model-neutral reconstruction

NUIF’s next research front is not “add an AI converter.” It is a coordinated resource, capture and reconstruction architecture with explicit truth boundaries. Images and fonts must survive as verified resources. Source-backed browser imports must retain authored/resolved evidence. Screenshot-only imports must remain honest probabilistic hypotheses. Every path converges through one core operation, validation, rendering and fidelity contract.

Decision summary

The recommended direction is:

1. define stable assets separately from immutable byte resources;
2. make .nuif a deterministic portable package after cross-writer proof;
3. grow the executable narrow PNG and static TrueType resource baselines only through named profiles and measured hostile-input budgets;
4. add a pinned browser-capture adapter separate from static source sync;
5. build screenshot reconstruction as a replaceable observation/proposal loop;
6. freeze a structural and visual evaluation suite before training;
7. consider adaptation or distillation only after the untuned loop exposes a repeatable learnable error distribution.

RFC 0010 and RFC 0011 remain proposed contracts. Their bounded package, narrow PNG/static-font and capture/reconstruction experiments are implementation evidence only for the named subsets; they are not published conformance or standards claims.

One core, two import lanes

Source-backed lane
HTML/CSS + browser execution + resource responses
      -> retained source + resolved observations
      -> deterministic adapter/lowering + explicit inference where needed
                              |
                              v
                    typed NUIF operations
                              |
                              v
                     core validation/apply
                              |
                              v
                      resource-aware NUIF
                              ^
                              |
Screenshot-only lane          |
pixels + context              |
      -> OCR/CV/grounding observations
      -> hierarchy/layout/resource hypotheses
      -> typed operations -> render/diff/correct

The lanes differ in evidence, not in their mutation authority. Both use the same typed operations. Neither provider can write core structs directly. A browser observation may support an exact resolved value under one pinned context, but it does not automatically reveal authored intent. A screenshot cannot establish source equivalence regardless of visual score.

Portable resource model

Four identities must remain distinct:

An asset points to a content descriptor containing media type, SHA-256 and byte length. A package path or external URL only locates candidate bytes; size and digest are checked before decoding. External resolution is opt-in. Opening a document never triggers network access.

Resource roles clarify hash and retention behavior:

• source: original encoded bytes;
• authoring: exact bytes needed to evaluate/edit semantics;
• derived: crop, trace, selected frame, conversion or generated result with input digests and transformation identity;
• cache: decoded pixels, GPU textures or acceleration state that can be deleted without changing the semantic document.

This avoids a common failure: storing only a decoded bitmap and calling the source image preserved, or hashing an editable asset by its current bytes and therefore breaking every reference after replacement.

Candidate .nuif package

The proposed first package is a deliberately small deterministic ZIP profile:

mimetype
manifest.cbor
document.cbor
blobs/sha256/<digest>

mimetype is first and stored. Manifest and document are deterministic CBOR. Every embedded blob is addressed by exact SHA-256 bytes. The first profile uses stored members only, fixed metadata and sorted ASCII paths to make independent writer byte equality attainable and to avoid compression-version variability.

There are three hashes:

• semantic document hash over canonical document.cbor;
• resource digest over each exact blob;
• package hash over the exact ZIP artifact.

Cache or report changes may change the package hash while leaving the semantic document hash untouched. Bare canonical forms remain .nuif.json and .nuif.cbor. Historical alpha .nuif raw files need read-only detection during migration; new .nuif output becomes the package only after RFC acceptance.

The package reader rejects duplicate or unsafe paths, symlinks, directories, encryption, split archives, unsupported compression, inconsistent headers, undeclared/missing blobs and digest mismatch. It does not extract to a filesystem. Exact byte fixtures, member/resource limits and two independent writers are acceptance gates.

Package-to-session handoff uses shared immutable buffers. The release gate passes an 8 MiB resource through package, handle map and session with the same allocation pointer while keeping handoff allocator traffic and retained bookkeeping below 1 MiB. This prevents a host from paying one full resource copy merely to enter the core.

Images

The original encoded image is authoritative. A semantic image asset records its resource digest and intrinsic interpretation; each image paint records fit, crop, transform, sampling, opacity and color conversion. Derived decoded pixels and GPU textures are caches.

PNG is the correct first format because its current W3C specification covers lossless encoded pixels, alpha and explicit colour metadata. The executable nuif-png-rgba8-0 baseline chooses an intentionally smaller contract: non-interlaced RGBA8, no ancillary metadata or one valid sRGB chunk, encoded samples interpreted as sRGB, straight decoded alpha, identity encoded orientation, declared fit/crop/sampling/opacity and bounded integer CPU composition. png 0.18.1 and zune-png 0.5.2 must emit identical RGBA bytes for the accepted fixtures; encoded resources remain digest-identical through package edits.

This avoids pretending that decoder agreement on simple images settles PNG Third Edition. The compatible nuif-png-basic-rgba8-1 profile now admits the lossless-to-RGBA8 subset: 1/2/4/8-bit greyscale and indexed images, RGB8, greyscale-alpha8, RGBA8 and valid palette/colour-key transparency. It preserves encoded bytes and requires exact normalized RGBA agreement between both decoders. It is separately named so profile zero never changes meaning.

Image-paint affine semantics are orthogonal to decoder choice. The executable matrix [a c tx; b d ty; 0 0 1] maps crop-local source coordinates forward into the fitted rectangle. The CPU reference inverse-maps destination pixel centers, clips to the entity, and rejects singular or numerically unbounded matrices. Flip, rotation and translation fixtures make composition order observable; live host trials are still required for vendor interoperability.

Decoded pixels are interned once per digest/profile in the renderer-independent scene and commands carry compact deterministic handles. A 64 MiB total is preflighted before each new inflation. The release gate retains one 1 MiB surface for 1,024 image instances under 8 MiB allocated and 4 MiB retained, and rejects a 64 MiB plus 16 byte declared total before the second decode.

Any broader profile still has to pin:

• accepted chunks and metadata conflicts;
• color-space precedence and output space;
• Exif orientation;
• conversion and premultiplication points for every accepted colour signal;
• sampling and compositing;
• encoded, pixel, decoded-byte, chunk and metadata limits;
• independent decoder and malformed-input fixtures.

16-bit/interlaced PNG, CICP/ICC/gamma/chromaticity, Exif, animation, perspective/tiling and host-specific affine equivalence are not claimed. A Linux/Windows/macOS CI matrix runs the profile, but the cross-platform claim remains withheld until its hosted artifacts pass. JPEG, WebP, AVIF, video and SVG follow as separate profiles. Freezing a frame or tracing a screenshot crop is a derived approximation, not recovery of the original asset. Generative upscaling/inpainting requires an explicit user policy and cannot silently become canonical source evidence.

Fonts

Exact typography depends on exact font bytes, face/collection index, variation axes, features, coverage, shaping inputs and renderer parameters. Packaging also depends on redistribution policy.

The proposed policy states are portable, private_authoring, linked, substituted and unavailable. OpenType fsType is preserved as machine- readable evidence, including restricted/preview/editable/no-subsetting/bitmap flags, but is not treated as a complete legal license decision.

The executable nuif-opentype-static-single-0 baseline accepts only one canonically packed, checksummed TrueType-outline sfnt face at index zero. Skrifa 0.46.2 supplies package-facing metadata after NUIF validates the directory, ranges, packing and checksums and directly checks required sfnt and OS/2 fields. A committed hb-info 14.4.0 capture independently checks Ahem metrics, family, tables and Unicode coverage. Exact bytes, family names, coverage, fsType, license expression and explicit embedding review must agree. Package encode/decode and caller-resolved linked bytes run the same validation. Four static TrueType fixtures are accepted, while six package trials distinguish portable, private-authoring, linked, substituted and unavailable outcomes. Each accepted inspection and packaged-font validation is also measured after warmup against a 4 MiB allocator-traffic and 2 MiB retained reference ceiling; these are implementation regressions, not format semantics. Six additional trials retain requested identity separately from a stable font asset, render with an available declared replacement as approximated, and emit no text command with item-level unsupported fidelity when replacement bytes or the font are unavailable.

This is intentionally not general OpenType support. TTC, CFF/CFF2, variable, color, bitmap, SVG and WOFF/WOFF2 sources, historic ambiguous permission combinations, subsetting, cluster-level fallback, arbitrary packaged-font shaping and cross-platform raster behavior remain separate fixtures and profiles. The configured three-OS parser/package matrix does not establish cross-platform raster behavior. Parser acceptance and fsType do not grant redistribution rights.

Browser capture can identify platform fonts used for a node and capture downloaded web-font response bodies. It generally cannot retrieve arbitrary local font bytes. A family/PostScript name is therefore never exact resource identity. Missing bytes produce a link, substitution or unavailable fidelity record instead of a false portable-font claim.

Source-backed browser capture

Static Tree-sitter source synchronization and live browser capture solve different problems. The former preserves source spans for a bounded authored subset. The latter runs a pinned browser to observe actual cascade, layout, fonts, resource responses, accessibility and pixels. They should correlate through provenance, not become one oversized adapter.

The first browser-capture profile records browser/protocol build, OS, viewport, DPR, page scale, locale, timezone, color/reduced-motion preferences, font environment, scroll/pseudo state, navigation identity, readiness/network policy and animation freeze. It collects:

• original HTML/CSS and stylesheet text where accessible;
• DOM snapshots including available frame/template/shadow content;
• boxes, inline text boxes, paint order and a bounded style set;
• downloaded image/font/style response bodies and hashes;
• platform-font usage and font readiness;
• accessibility tree;
• reference screenshots with exact parameters.

Canvas, WebGL, video and worklets are bounded observation surfaces; a frame can be preserved without pretending its generating program was reconstructed. Cookies, authorization headers, credentials, storage and secret form values are not exported. Scripts remain inert.

Multiple viewports and states are more valuable than one oversized capture: they constrain layout hypotheses and permit held-out responsive evaluation.

The automated nuif-cdp-live-0 segment now implements that boundary for one loopback fixture and exact Chrome for Testing 152.0.7977.64. It starts fresh temporary profiles, retains a structured runtime context, waits for the exact navigation loader and declared freeze/readiness point, captures bounded DOM/layout/background/font/accessibility/resource/PNG evidence, and replaces opaque browser node IDs with deterministic preorder identities. Four runs at 360, 768, held-out 900 and repeated 360 px retain exactly the expected five response bodies and repeat the narrow capture bytes. Five exercised query/cookie/storage/authorization/header canaries are absent from serializable capture, observations, proposals and package bytes. The two fitted viewports beat the one-viewport freeform baseline on the held-out fixture.

The separate bounded nuif-layout-inference-0 artifact ranks row stack, column stack, Grid, linear constraint and fixed freeform candidates using only the 360/768 px observations. It then evaluates the untouched 900 px holdout, where the selected constraint records 0.0626 normalized error versus 0.2918 for freeform. All alternatives and exact geometry observation identities are retained; confidence is raw and uncalibrated, and the result remains inferred. The trial tests a mechanism on one fixture, not general accuracy or recovery of original authored intent.

This is a falsifiable local baseline, not the entire profile described above. Cross-browser/OS reproduction, opaque frames and response bodies, full matched-style/source correlation, canvas/video frame capture, authenticated sites and licensed real-page evaluation remain open. WebDriver BiDi is the standards-track transport to revisit as its implemented evidence surface grows; Playwright is the higher-level candidate when NUIF owns a real multi-engine matrix and can make one tool the browser-version authority.

Screenshot reconstruction

A screenshot supplies visible samples but not the unique scene graph or layout program. The recommended pipeline is:

screenshots + contexts
  -> OCR and baselines
  -> deterministic regions, colors, edges, repetitions and asset candidates
  -> optional replaceable UI grounding
  -> typed observation graph with confidence and evidence regions
  -> replaceable reasoner proposes hierarchy/layout and NUIF operations
  -> core validates and applies atomically
  -> deterministic layout/render
  -> text/structure/geometry/resource/visual differences
  -> bounded corrective operations

The model emits typed operations, not an unconstrained full document or code to execute. Invalid and stale transactions fail without partial state. High- resolution full views, overlapping tiles and semantic crops share explicit coordinate transforms; duplicate or conflicting observations remain visible.

The result contains a valid document or no-result, accepted operation log, observations, derived resources, item fidelity, alternatives/abstentions, evaluation report and exact pipeline artifact identities.

Evaluation before training

The benchmark has separate synthetic-exact, licensed real screenshot and source-backed suites. Synthetic NUIF rendering provides exact entities, properties, operations and resources. Real images need human-reviewed visible targets and must preserve ambiguity. Source-backed cases evaluate retained bytes and observations unavailable to the screenshot-only route.

Required metrics include:

• valid operation/document rate;
• OCR region recall, character/word error and baselines;
• element precision/recall and hierarchy error;
• property/geometry accuracy;
• held-out viewport behavior;
• exact resource digest only when bytes exist;
• provenance/fidelity honesty;
• accessibility evidence where justified;
• raw pixels, FLIP, SSIM and pinned LPIPS diagnostics;
• calibrated confidence, abstention and risk/coverage;
• latency, peak RAM/VRAM, iterations and cost.

No pixel score is sufficient. A page-sized screenshot can be visually perfect and semantically useless. Structural/text/resource/edit-task metrics prevent that reward shortcut. Dataset splits group by origin, template, component, font, resource and generator; near duplicates cannot cross splits.

The executable nuif-reconstruction-corpus-manifest-0 turns that rule into a bounded audit. It pins the data snapshot, dataset card, evaluator and every input/target by digest; records public/restricted/withheld disclosure and evaluation/calibration/adaptation/redistribution permission independently; and rejects exact artifact or declared family reuse across adaptation, calibration, validation and test. Private/authenticated records also require explicit authorization and a withdrawal-policy artifact. This is declaration integrity, not automated legal review or duplicate discovery; real records and their group assignments still need independent human/tool review.

The ablation ladder is deterministic OCR/CV, one-shot reasoner, observation- assisted reasoner, hierarchical crops, multi-viewport ranking, correction loop, then any tuned or distilled student. Every addition uses the same frozen holdout and budget.

Adaptation and distillation

Training is justified only after the untuned loop and error taxonomy are reproducible, rights-cleared traces exist, and the remaining errors appear learnable. Training examples contain input hashes, observation versions, proposals, diagnostics, accepted operations, intermediate renders/differences and final package/fidelity reports. Positive sequence targets are validated accepted transitions, not raw model transcripts.

Compare prompt/schema/tool improvements and retrieval before fine-tuning. If adaptation remains justified, compare ordinary supervised tuning, low-rank adaptation and quantized low-rank adaptation under equal data and evaluation. Quantized adaptation is a memory technique, not an accuracy claim.

Sequence-level distillation may train a smaller student from the best evaluated teacher pipeline. The teacher is a measured system of tools plus a model, not a provider name. Distillation transfers errors too, so render validation and held-out evaluation remain mandatory.

Models, processors, adapters and datasets are separately versioned optional artifacts with digests, model cards, dataset datasheets, license lineage and training manifests. They never redefine nuif-core or travel as ordinary document resources.

The executable provider boundary uses a deliberately small canonical wrapper, not a new AI bill-of-materials vocabulary. It binds NUIF capabilities, execution modes and observation/proposal profiles to exact implementation, model, processor, adapter, quantization, prompt and tool artifacts. Observation bundles carry the complete manifest registry, so a digest cannot dangle and a proposal cannot substitute an unpublished provider before mutation. Released or learned providers point to content-addressed SPDX 3.0.1 or CycloneDX 1.7 inventory; learned providers also point to a model card. This complements runtime packaging such as MLflow or ONNX external data without making either a required NUIF dependency.

Private/authenticated captures default to local processing, no retention and no training. Remote transfer, telemetry, retention and training are independent consent/policy decisions.

Maturity boundary

The current 0.1.0-alpha.3 label belongs to the developer editor application. It provides no evidence that the broad image/font resource, portable browser capture or screenshot reconstruction accuracy profiles are complete. A deterministic package, narrow PNG/static-font segments, fixed provider-input contracts and one pinned local live-browser segment are implemented, but their deliberately narrow evidence does not promote the broader profiles.

Promotion requires the package/resource cross-writer fixtures, pinned capture reproduction, baseline/closed-loop/calibration harness, leak-resistant licensed evaluation data, independent result reproduction and at least one real edit workflow that benefits from the inferred semantics. Until then the work is research and proposed specification text, not a standard or production reconstruction promise.

Primary research records

• nuif:research:resource-packaging-and-source-capture-synthesis
• nuif:research:model-agnostic-screenshot-reconstruction-and-training
• nuif:research:provider-artifact-manifests-and-ai-boms
• nuif:research:epub-ocf-package-container
• nuif:research:oci-resource-descriptors
• nuif:research:opentype-font-embedding-and-portability
• nuif:research:ttf-parser
• nuif:research:fontations
• nuif:research:chromium-source-backed-ui-capture
• nuif:research:live-chromium-cdp-capture
• nuif:research:design2code-real-world-benchmark
• nuif:research:pix2struct-screenshot-parsing-pretraining
• nuif:research:screenai-ui-annotation
• nuif:research:confidence-calibration-and-selective-prediction
• nuif:research:lora-low-rank-adaptation
• nuif:research:qlora-quantized-adaptation
• nuif:research:sequence-level-knowledge-distillation

Canonical module.

NUIF — Neutral User Interface Format

Authored intent, resolved state, stable identity and explicit loss accounting in one portable document model for user interfaces.

Citation metadata is provided in CITATION.cff. The current software citation identifies the latest published editor prerelease. It does not cite the draft specification as an accredited standard.

Problem · Scope · Architecture · Repository · Method · Status · Contributing · License

Problem

Interface designs move between design editors, design systems, source frameworks and automation tools by regeneration. Each export flattens authored constraints, components, token bindings and provenance into pixels, a vendor scene graph or generated code; each import guesses them back. Three consequences follow: round trips lose information, the loss is silent, and entity identity does not survive the trip, so later edits cannot be synchronized as patches.

NUIF treats portability as a synchronization problem. One canonical document keeps the authored intent and the resolved evaluation state side by side under stable identifiers, records every lossy mapping as a typed fidelity class, preserves data it does not understand, and exposes every mutation as a replayable semantic operation. Editors, runtimes and adapters become peers of the document rather than owners of it.

Scope

Architecture

flowchart LR
  subgraph Clients
    CLI[CLI]
    Editor[Reference test editor]
    WASM[Browser and plug-in WASM]
    QA[Automated conformance clients]
  end

  subgraph Engine["Rust reference engine"]
    API[Headless API]
    Proto[Operations, transactions, patches]
    Doc[(Canonical document<br/>containment tree + relationship graphs<br/>authored intent)]
    Eval[Layout evaluation<br/>per evaluation context]
    Res[(Resolved snapshot<br/>boxes, shaped text, diagnostics)]
    Scene[Render scene]
    Codec[Codecs<br/>canonical text, deterministic CBOR]
    Query[Query and diagnostics]
  end

  subgraph Peers["Adapters (peers, not parents)"]
    HTML[HTML/CSS, Svelte, React]
    SVG[SVG]
    Design[Penpot, Figma]
    Native[SwiftUI, Compose, Flutter]
  end

  Ref[Renderer backends<br/>Vello/wgpu, CPU reference]
  Conf[Conformance suites<br/>fixtures, replay, reference images]

  CLI --> API
  Editor --> API
  WASM --> API
  QA --> API
  API --> Proto --> Doc
  Doc --> Eval --> Res --> Scene --> Ref
  Doc <--> Codec
  Doc --> Query
  Codec <--> Peers
  Peers -- fidelity records + correspondence --> Doc
  Ref --> Conf
  Res --> Conf
  Proto -- replay log --> Conf

Principles that the diagram encodes:

• the canonical document is the only owner of authored state; every client, including the editor, mutates it through semantic operations;
• resolved state is derived per evaluation context and never overwrites authored intent;
• identity is semantic and independent of path, order and geometry;
• adapters emit fidelity records (lossless, representable, approximated, preserved_unrenderable, unsupported) and correspondence records; silent loss is a conformance failure;
• unknown extensions survive transit byte-for-byte;
• collaboration is a profile above canonical documents, not part of them;
• the headless API and CLI are the primary test surface; GUI automation is supplementary.

Repository

Method

Research is structured data. Each record in research/items/ has a stable identifier, a primary source with locators, a confidence value, typed relations to claims and other records, and links to the specification, decisions, code and experiments it informs. research/coverage.yaml maps every architectural front to its evidence and status (covered, experiment-required, ongoing), so gaps are detected structurally. Claims become normative only through the RFC process and an executable conformance fixture.

Testing is designed for automated trial loops: generate or load a document, apply operations, export and import through adapters, compare canonical forms, resolved layouts and reference images, minimize failures, and record a machine-readable report. The harness design is in conformance/HARNESS.md.

Status

Gates B through H are complete under the bounded, quantified criteria in research/AUDIT.md. The workspace executes structural validation, anchored atomic operations, replay/inversion, canonical text and deterministic CBOR, measured hostile-input limits, responsive profile-0 layout, bounded explicit fixed/fr Grid tracks and placement, exact CPU rasterization, pinned NUIF/Taffy/Chrome layout trials, seeded reports and headless and native-shell editor drivers. Gate C covers sparse row/column flow, explicit placement and spans without a schema-loss exemption. Gate D pins shaping, outlines, hard-line layout, encoded-sRGB paint and integer composition; scene and raw-RGBA hashes reproduce on macOS/aarch64, Linux/aarch64 and Linux/x86_64, while PNG encoding is non-normative and paths, images, instances and extension paint remain property-attributed fidelity records. Seven retentive source/package adapter profiles are integrated across HTML/CSS, SVG 2, DTCG 2025.10, Penpot v3 packages, static React JSX and static Svelte, with import, export, synchronization, hostile-input checks and CLI conformance; Svelte additionally passes a pinned official-compiler oracle. An eighth executable profile covers normalized Figma Plugin API snapshot and mutation-plan mapping plus a compiled no-network review shell, without claiming live host execution. The ninth is a one-way bounded HTML/ARIA accessibility projection whose computed role/name/state surface agrees across pinned Chromium, Firefox and WebKit test engines. The tenth maps the bounded behavior sidecar to native button activation, hidden visibility and an ARIA status region through one CSP-hash-restricted finite runtime, with event-by-event agreement in the same three engines. A machine-audited inventory separates these executable profiles from four researched or externally bounded targets. Complete fixture authoring, AccessKit-driven deterministic GUI trials, standard-library-only Python v0 reproduction, metadata-free register and existing-tree collaboration checkpoints, a pinned Automerge operation-transport oracle, hostile editor interaction trials, a scaling benchmark suite, native host packaging and cross-checked WebAssembly and MCP developer surfaces are automated. The native shell exposes the complete model-backed profile-zero editing surface while leaving future-profile sections of the draft UI specification explicit; concurrent entity creation and collaboration garbage collection, a foreign tree materializer, a general-purpose second implementation, signed native distribution and external interoperability review remain incomplete.

Gates I through L are not complete. The package segment of Gate I is now executable: .nuif is a deterministic bounded package, stable assets and exact resources have distinct identities, resolution is explicit, and the CLI/editor preserve package resources. cargo xtask gate-i-package records cross-writer, fixpoint, identity, resolver and hostile/one-over evidence. cargo xtask gate-i-image independently decodes the narrow nuif-png-rgba8-0 subset, preserves exact encoded resources and repeats resource-aware CPU rendering. cargo xtask gate-i-font compares the narrow nuif-opentype-static-single-0 subset across two Rust parser families, enforces exact package metadata and explicit embedding review, and rejects malformed and one-over resources. Gate I still lacks the broader PNG and OpenType matrices, external writer and successful hosted cross-platform package/media evidence. The CI workflow now runs all three narrow resource gates independently on Linux, Windows and macOS and archives each platform report; that configuration does not become reproduction evidence until the hosted jobs pass. RFC 0011/specification 14 have executable provider-neutral observation with canonical artifact-manifest registries, browser/screenshot baseline, typed-proposal, flat-copy rejection, calibration and finite-loop primitives. The local Gate J segment now drives pinned Chromium, retains exact resources/font/accessibility evidence, excludes exercised secret canaries and beats a one-view baseline at a held-out viewport. Gate J still requires portable cross-OS/browser and broader source evidence; Gate K still requires reconstruction accuracy and an independent evaluator. No LoRA/QLoRA artifact or distillation is implemented. The editor’s 0.1.0-alpha.3 version is not maturity evidence for these research fronts. Specifications remain drafts and no standards conformance profile is published. The separate bounded web-accessibility gate projects portable semantics to inert HTML/ARIA and compares computed role, name and state across exact Playwright Chromium, Firefox and WebKit engines; it does not claim native platform or application-behavior equivalence. The bounded behavior gate first binds one canonical program to a deterministic package resource and independently inspects its ZIP bytes, then executes the same stable-identity state machine through Rust and Node runtimes. The separate web-behavior gate lowers that trace contract to native button clicks, hidden visibility and an ARIA status region through one exact CSP-hash-authorized runtime and compares every event in pinned Chromium, Firefox and WebKit. Timers, internal events, numeric computation, networking, arbitrary scripts, native UI and assistive-technology speech remain excluded.

Run the automated baseline:

cargo xtask all # installs/reuses the pinned browser and runs every gate
cargo xtask browser-install # optional browser prefetch
cargo xtask gate-wasm # pinned-browser initialization and Node/native byte parity
cargo xtask wasm-package # downloadable direct-browser developer archive
cargo xtask gate-mcp # current stateless stdio protocol and native byte parity
cargo xtask mcp-package # live-tested host developer archive
cargo xtask gate-web-behavior # three-engine native web behavior lowering
cargo xtask gate-behavior-package # inert package attachment and independent ZIP checks
cargo xtask cli-package # exercised standalone developer-tool archive
cargo xtask trial 24301 100
cargo xtask gate-b # 10,000 patches; raster sample every 100 patches
cargo xtask hostile-inputs # boundary/one-over time and allocator report
cargo xtask reduction-profile # hierarchical/choice reduction and fixture evidence
cargo xtask editor-hostile-inputs # semantic, parser and snapshot rejection report
cargo xtask fuzz-smoke # bounded AddressSanitizer campaigns over five core surfaces
cargo xtask adapter-audit # research/profile/gate coverage for all advertised targets
cargo xtask diagnostic-audit # public model/layout/trial diagnostic registry drift
cargo xtask performance # portable budgets plus one execution of every Criterion path
cargo xtask codec-benchmark # codec size, latency, allocation and admission evidence
cargo xtask gate-c # NUIF/Taffy/pinned-Chrome layout report
cargo xtask gate-d-text # HarfBuzz golden shaping + separate raster report
cargo xtask editor-trial # author the v0 fixture and emit editor evidence
cargo xtask editor-gui-trial # exercise AccessKit and reproduce shell pixels
cargo xtask editor-package # build, smoke-test and archive the host application
cargo xtask editor-launch # package and open the native application
cargo xtask editor-install --user --channel source # persistent local build
cargo xtask editor-doctor --user # verify receipt, binary and integration
cargo xtask editor-update --user --channel alpha --check # resolve only
cargo xtask editor-update --user --channel alpha # verified explicit update
cargo xtask editor-rollback --user # reactivate the retained previous build
cargo xtask editor-uninstall --user # remove only marked managed paths
cargo xtask gate-f # retentive HTML/CSS subset synchronization
cargo xtask gate-f-v0 # full-v0 model sync plus editor/CLI source bridge
cargo xtask gate-g # independent Python v0 parse/write/layout/render
cargo xtask gate-h # exhaustive collaboration register convergence
cargo xtask gate-i-package # deterministic package/resource evidence
cargo xtask gate-i-image # independent RGBA8 PNG/resource/render evidence
cargo xtask gate-i-font # independent static TrueType/resource/policy evidence
cargo xtask gate-figma # pure Plugin API snapshot/plan mapping (not a live host)
cargo xtask gate-behavior # package binding plus deterministic Rust/Node behavior traces
cargo xtask capture-baselines # bounded capture/reconstruction contract evidence
cargo xtask gate-j-live # pinned live Chromium/resource/secret/held-out evidence
cargo xtask gate-accessibility # three-engine computed accessibility evidence
cargo run --locked -p nuif-cli -- fixture v0-responsive-card /tmp/v0.nuif
cargo run --locked -p nuif-editor -- --headless \
  --script conformance/fixtures/v0-responsive-card/editor-trial.jsonl \
  --document /tmp/v0.nuif --output /tmp/edited.nuif
cargo run --locked -p nuif-editor # launch the native editor

cargo xtask all bootstraps the pinned Python research-validator environment, wasm-bindgen toolchain and Chrome for Testing under ignored target/, then runs research validation, Rust verification, WebAssembly/native API parity, the short full-raster trial, the 10,000-patch Gate B trial, release-mode hostile-input, codec-decision and performance trials, the Gate C differential layout trial, both Gate D text/render trials, complete headless/native editor trials, bounded retentive adapter bridges, the bounded Rust/Node behavior differential, the independent Gate G reproduction, exhaustive Gate H collaboration-register convergence, the Gate I package, narrow-image and narrow-font segments, and the bounded capture/reconstruction contract report. Each measured run leaves a JSON report or snapshot under target/; target/verification-manifest.json indexes the complete evidence set and records success or the first failed step. CI archives both the individual evidence and this manifest.

Contributing

Research, specification, conformance, implementation and adapter contributions are accepted; see CONTRIBUTING.md for the record schema, the writing register and the single-line commit rule. Governance is described in GOVERNANCE.md; security reports in SECURITY.md.

License

Reference code is dual-licensed under Apache-2.0 or MIT (LICENSE-APACHE, LICENSE-MIT). The repository has not adopted specification-wide copyright or patent terms. docs/whitepaper/08-governance-and-standardization.md records the licensing requirements that precede standards-track publication.

Canonical source.

Research and implementation roadmap

The evidence gates and quantified acceptance criteria are normative for project planning in research/AUDIT.md; these phases describe implementation order only.

Phase 0 — foundation (complete)

Exit: research graph schema, architectural RFCs, compilable core seams, CI and v0 falsification fixture exist.

Phase 1 — canonical model (complete)

Implement typed properties, relations, components, tokens, extensions, deterministic IDs, validation and operation replay. Exit: structural conformance suite and canonical hash stability.

Phase 2a — responsive layout falsifier (complete)

Implement freeform + stack/flex subset and a pinned NUIF/Taffy/Chrome context matrix. Exit: responsive-card layout agreement at three viewports, measured per-fixture bounds and classification of every generated divergence.

Phase 2b — bounded explicit Grid (complete)

Profile 0 now defines positive fixed/fr tracks, sparse row/column auto-flow, zero-based explicit placement, positive spans, no implicit tracks and bounded resource use. The independent NUIF evaluator implements those rules directly; Taffy and CSS are lowering targets, not hidden runtime dependencies. Gate C exercises simple, explicit and spanning Grid cases and passes with no classified, blocking or unexplained divergence. Intrinsic, percentage, named, repeated, subgrid, masonry and implicit CSS tracks remain outside this bounded profile.

Phase 3 — visual/text (complete for profile 0)

Pinned Ahem/HarfRust shaping matches HarfBuzz glyph goldens; unhinted Skrifa 0.46.2 outlines match normalized hb-vector goldens; hard-line layout, rectangles, ellipses, encoded-sRGB color and integer composition have normative scene/raw-RGBA baselines across macOS/aarch64, Linux/aarch64 and Linux/x86_64. PNG hashes remain deterministic artifact diagnostics but are not pixel-conformance boundaries. Path, image, instance and extension paint remain explicit unsupported/preserved fidelity rather than hidden fallbacks. Full UAX #14 soft wrapping and expanded vector paints belong to a future profile.

Phase 4a — bare serialization/protocol (complete for profile 0)

Canonical text + deterministic CBOR plus patch/diff/query CLI. Exit: byte-stable cycles and measured hostile-input limits. The separate active codec decision gate records four-scale size, latency, allocation, canonicalization and decode-then-select evidence. Both implemented codecs pass opaque-data edit preflight; schema candidates are not timed on partial models. Cap’n Proto is the next candidate only after a complete mapping. This phase does not include the portable .nuif package, images or general font resources.

Phase 4b — portable package and resources (active; container segment implemented)

RFC 0010 now has a package layer above nuif-codec, stable assets in the core, explicit verified resource resolution and package-preserving CLI/editor I/O. The manual writer and an independent ZIP writer produce identical bytes; semantic/resource/package hashes obey distinct fixtures; hostile archives and package/resource/count one-over cases are blocking through cargo xtask gate-i-package. Existing raw .nuif inputs migrate read-only and new bare forms use .nuif.json/.nuif.cbor. The executable nuif-png-rgba8-0 baseline independently decodes a deliberately narrow PNG subset. The separately named nuif-png-basic-rgba8-1 expansion now covers non-interlaced lossless-to-RGBA8 greyscale, indexed, RGB, greyscale-alpha and RGBA forms plus valid transparency; both retain encoded bytes and repeat package-aware CPU image rendering through cargo xtask gate-i-image. Gate I remains open for 16-bit/interlaced/colour-managed PNG and live host/GPU affine equivalence. Package/session handoff and decoded image surfaces now have measured sharing, total-byte and allocation ceilings. Static-font inspection and packaged validation now have warmed allocation ceilings across every accepted fixture. A Linux/Windows/macOS resource-gate matrix is configured; successful hosted artifacts are still required before a cross-platform reproduction claim. The separate nuif-opentype-static-single-0 baseline validates one exact static TrueType face through package encoding/resolution, compares Skrifa results with a pinned HarfBuzz metadata capture and rejects malformed/policy/one-over cases through cargo xtask gate-i-font. TTC, CFF/CFF2, variable/color/bitmap/WOFF2 fonts, cluster-level fallback, arbitrary packaged-font shaping, successful hosted cross-platform evidence and external implementations remain open. Stable text-to-font asset bindings now distinguish requested, replacement and unavailable identities with six blocking layout/render fidelity trials.

Phase 5 — editor (complete for the headless profile-0 instrument)

The entire v0 fixture is authored from an empty document through identity-addressed semantic actions. Direct generation, editor output and operation replay are byte-identical, and the editor writes canonical document, context, layout, scene, CPU raster and fidelity report artifacts. The Rust-native Masonry shell from ADR 0006 and the later Svelte/WASM demonstration are non-normative interface work and cannot redefine this headless result.

Phase 5b — native editor research preview (complete through alpha.3)

The native shell exposes the semantic driver through identity-backed canvas selection, a file menu with canonical and declared adapter import/export routes, document-aligned background grid and pixel rulers, layer and component browsing, insertion tools, evaluation widths, zoom, inspector transactions, bounded explicit Grid authoring and source-built developer installation. Captured pointer movement for freeform children previews locally and commits one semantic position operation on release; it snaps to whole pixels by default and supports Control-suspended snapping. Stack/Flex drags infer the effective responsive axis from resolved siblings and commit one same-parent Move; unchanged order creates no history, while Grid, Constraint, cross-parent and instance-child cases fail closed. Freeform selections expose eight handles; managed-layout children expose the three trailing handles. Resize previews resolved geometry and atomically commits the changed fixed axes plus an anchored freeform position when required; Shift preserves corner aspect ratio and invalid, root or semantically ineffective paths fail closed. Grid track, flow, atomic item position and span edits use the same validated operations as the headless and accessibility surfaces. Open packages pass their digest-verified embedded resources through the same bounded session used by CLI render/snapshot, so the narrow RGBA8 image segment renders without implicit fetching. cargo xtask editor-gui-trial, cargo xtask editor-hostile-inputs and cargo xtask editor-install-trial exercise the semantic, visual, adversarial and lifecycle boundaries. The broader apps/editor/UI-SPEC.md remains a draft; multi-selection, persisted aspect-ratio constraints, object smart guides, cross-parent/tree drag, Grid/Constraint reorder and managed leading-edge resize, token authoring and expanded paint are not claimed by this phase.

Packages declaring capabilities outside the editor’s explicit empty support set open structurally but read-only. The driver, accessibility surface and changed-package save boundary return the exact missing set, while an unmodified copy stays byte-identical. This conservative boundary is included in the editor hostile-interaction gate.

Phase 5c — browser and plug-in binding (complete for nuif-wasm-api-0)

The byte-oriented WebAssembly module wraps nuif-api, canonical text/CBOR, deterministic packages, explicit package-capability negotiation and semantic patches without copying the model into JavaScript. A Node/native differential checks exact edited bare and package bytes, packaged-resource preservation and typed missing-capability failures. Structural requirement-bearing packages are read-only until complete-set authorization, including semantic patches and mode conversion; the direct-browser target initializes its package API in pinned headless Chrome. Its JavaScript, TypeScript and WASM are packaged as a CI and tagged-release developer artifact. The module declares no filesystem, network or host-document authority. The Figma review shell now compiles against pinned official typings and crosses a mock snapshot into the Rust core, but its assigned-ID live-host run remains separate. Browser-layout execution, a WASI CLI, npm publication and live Figma, Affinity and Canva adapters remain separate profiles and version streams.

Phase 5d — external agent binding (complete for nuif-mcp-tools-0)

The MCP process is a stateless stdio adapter over the same API and semantic patch layer. Its four inline-text tools carry no host authority, support only the current 2026-07-28 lifecycle, and are differentially checked against the native CLI through a real child process. Five native release jobs package and attest the separately versioned binary; source installation remains available without an application store. Live compatibility with named third-party MCP hosts, large-document resource handles and any authenticated HTTP service are separate trials and are not claimed by this phase.

Phase 5e — direct SDK and foreign binding boundary (direct SDK complete)

nuif-api::NuifDocument is the package-aware, byte-oriented façade over the canonical codecs, verified package/resources and typed session operations. Text/CBOR load, validation, transaction application, hashes, undo/redo and bare/package export have one implementation; the WASM binding delegates to it and the system benchmark suite measures direct text, CBOR and package calls. The façade separates inert structural package access from session authorization: requirement-bearing packages reject evaluation, mutation, history and mode conversion until exact complete-set negotiation succeeds. The unified performance gate executes every Criterion path once and audits per-profile adapter direction coverage; controlled benchmarks include package capability negotiation and all ten integrated adapter profiles without treating shared CI timing noise as a regression threshold.

No stable C ABI is claimed while the semantic API remains 0.0.x. ADR 0011 requires a separately reviewed unsafe nuif-ffi boundary, stable ownership and error contracts, cbindgen header/symbol checks, sanitizer-backed C consumers, pinned UniFFI Swift/Kotlin consumers and real XCFramework/AAR packages before that surface becomes integrated. This is a promotion gate, not missing logic that should be guessed into the core.

Phase 5f — standalone developer CLI package (complete locally)

nuif-cli-tools-0 is packaged for the same Linux x86-64, Linux AArch64, Windows x86-64, macOS Apple Silicon and macOS Intel release matrix as the native tools. Each archive contains the binary, licenses, developer instructions and a smoke report produced by that release binary. The gate requires version and capability identity, then generates, validates, canonicalizes and inspects a real profile-0 document before the archive can be indexed. Sibling manifests bind the source revision, platform, binary/archive digests, command inventory and explicit filesystem/standard-stream authority; the release index records the packages under tools and includes a separate CycloneDX SBOM. Local macOS/AArch64 packaging passes. Successful hosted jobs and attestations remain release-time evidence, not a claim made from workflow configuration.

The CLI declares an empty extension-capability support set. Capability-bearing packages remain available for structural inspection, bare extraction and exact copying, while evaluation, external-format conversion, semantic package rewrites and package-mode changes fail with the exact requirement set. Native package import/export preserves resources and manifest requirements.

Phase 6a — first adapters/sync falsifier (complete for bounded HTML/CSS profile 0)

nuif-html-css-0 maps a declared container/text/finite-token subset through real DOM/CSS syntax with byte-span correspondence. Text, token and four-edge padding edits change only their six spans; comments and unmapped markup survive exactly; unsupported semantics have target/property fidelity. HTML/CSS was intentionally tested before SVG because Gate F and the architecture stop condition concern minimal source patches. This narrow profile remains independently automated even after the full-v0 follow-on; arbitrary HTML/CSS and SVG remain broader adapter work.

Phase 6b — full-v0 HTML/CSS sync (complete)

nuif-html-css-v0 carries the complete responsive-card model through 181 retained correspondences. The full trial applies eight local token/padding/text/responsive edits while preserving all other source bytes and opaque payloads; the editor bridge applies name and width edits through semantic actions and the public CLI, then re-imports to byte-identical canonical NUIF. Browser path rendering, instance materialization and unknown visuals remain explicit target limitations.

Phase 6c — bounded SVG sync (complete)

nuif-svg-0 maps a fixed surface, freeform groups, rectangles, ellipses and literal pinned-font text to SVG 2 XML. The trial applies seven identity, geometry, paint, text and accessibility edits through 45 retained correspondences, preserves unmarked XML, and rejects scripts, external resources and unsupported SVG geometry before synchronization.

Phase 6d — bounded DTCG sync (complete)

nuif-dtcg-scalar-0 maps flat boolean, string and number tokens to the Design Tokens Format Module 2025.10. Namespaced metadata retains NUIF document and token identity and distinguishes integer from real values; the trial applies eight edits through 21 correspondences while preserving unknown extension bytes. Groups, aliases, composite types and token-local extensions require a token-model RFC and a separate profile.

Phase 6e — adapter inventory (complete for advertised targets)

adapters/index.json enumerates twelve advertised targets. The blocking adapter audit requires a primary research record, integration surface, next bounded profile and exclusion boundary for every target; executable entries additionally require a crate, profile document and routed conformance gate. Ten profiles are integrated: the seven retentive HTML/CSS, SVG, DTCG, Penpot, static React JSX and static Svelte profiles; nuif-figma-plugin-snapshot-0; the one-way nuif-web-accessibility-0 projection; and the one-way nuif-web-behavior-0 host lowering. The Figma profile proves normalized mapping, CLI parity and static compilation of its no-network shell, not plug-in execution in Figma. Affinity, Canva, SwiftUI, Jetpack Compose and Flutter remain explicitly researched or externally bounded rather than carrying unsupported implementation claims. Affinity is a user-mediated SVG bridge until a public API exists; Canva is a stable-API current-page app profile with Connect and marketplace claims kept separate. Svelte uses Tree-sitter only for retained spans and exact official svelte/compiler 5.57.0 as its foreign parse/compile oracle.

Phase 6f — bounded web accessibility projection (automated)

nuif-web-accessibility-0 lowers ten roles, role-specific Boolean states and five stable-identity relationships to inert native HTML/ARIA. It rejects unsupported roles and state combinations, ambiguous direct/relationship names, unnamed labels and duplicate relationships before output. The foreign oracle pins Playwright 1.62.1 and its Chromium, Firefox and WebKit engines, then compares computed role, accessible name and every admitted Boolean state for eleven entities. The first macOS/arm64 run has identical full snapshots across Chromium 151.0.7922.34, Firefox 153.0 and WebKit 26.5. Native platform APIs, keyboard/focus traces, application behavior and broader semantic value types remain separate work.

Phase 6g — bounded behavior state-machine sidecar (automated)

nuif-behavior-state-machine-0 executes stable-entity activate events through one flat deterministic state machine. Ordered guarded transitions, sequential Boolean/string actions, visibility/announcement effects, required capability refusal and explicit optional no-op degradation have complete traces. The Rust reference and independently written Node interpreter agree for both capability sets over the five-event fixture. RFC 0012 now carries the same program as one canonical-CBOR, content-addressed source resource under nuif-behavior-package-resource-0 without adding it to the semantic Document. The package gate proves document/package hash separation, exact round trip, hostile refusal and independent Python ZIP inspection; generic package decode remains inert, the SDK reports exact missing package requirements before a full-support claim, and runtime effect authorization stays separate. Timers, internal events, numeric computation, navigation, animation, networking, scripts, native effects and browser effects beyond the following projection remain separate profiles and wire-design work.

Phase 6h — bounded web behavior projection (automated)

nuif-web-behavior-0 composes the behavior sidecar and accessibility projection without accepting authored JavaScript. Enabled native button/switch clicks select the same transitions as the reference runtime; visibility uses hidden, and one advisory announcement per transition uses an unfocused polite status region. Delimiter-safe program data is interpreted by one finite runtime authorized by an exact CSP hash. Separate pointer and alternating Enter/Space keyboard sequences pass all five events’ state, transition, retained visibility and announcement comparisons in Playwright Chromium 151.0.7922.34, Firefox 153.0 and WebKit 26.5 on macOS/arm64. Checkbox, radio, disabled-control, focus, navigation, animation, screen-reader speech, native UI and arbitrary script remain explicit exclusions.

Phase 7a — collaboration property registers (complete)

nuif-collab-registers-0 keeps causal metadata outside canonical documents and materializes concurrent register-like semantic operations through operation-set and replica-log algorithms. Every delivery of the three-replica trial converges, and distinct concurrent values remain explicit property conflicts.

Phase 7b — bounded existing-tree structural collaboration (complete)

nuif-collab-tree-0 implements move, reorder, trash deletion and later rescue for identities already present in one canonical base. Unique Lamport ordering plus cycle rejection preserves one-parent/acyclic structure; RGA-style stable origins preserve deterministic sibling order without putting clocks, tombstones or position IDs in canonical NUIF. Move/move, delete/move, deleted-parent, delete/descendant-move, cycle and anchor conflicts remain explicit. Two materializers converge over all 5,040 deliveries of a fixture that includes a causal moved-position anchor, plus a 4,096-change scale trial. Pinned Automerge 3.4.1 reproduces the exact immutable operation set under three merge orders, duplicate merge and save/load; it is a foreign transport oracle, not an independent implementation of the tree algorithm. Concurrent creation, causally stable garbage collection, combined property/structure transactions and external tree-materializer reproduction remain future profiles.

Phase 8a — mechanical independent reproduction (complete for v0 profile 0)

The standard-library-only Python implementation reads, writes, lays out and rasterizes the v0 profile without importing, invoking or linking the Rust packages. Its differential trial is exact at 360, 768 and 1,440 pixels and stays in the unified CI loop.

Phase 8b — external reproduction and standards review

Package the schema/conformance kit and obtain reproduction by an externally authored implementation. External provenance, interoperability review, neutral governance and a published conformance profile remain prerequisites for credible standards status; the in-repository mechanical reproduction and source adapter do not establish them.

Phase 9a — canonical research publication (complete)

cargo xtask docs-check compiles the repository Markdown into one machine-readable catalog. cargo xtask docs-build renders that catalog without a second editable documentation source. cargo xtask docs-paper composes the thirteen canonical whitepaper modules into a working technical manuscript and a verified PDF. Pull requests build retained artifacts, while default-branch workflow runs deploy the static site through GitHub Pages. CITATION.cff describes the tagged alpha.3 software release; no DOI or peer-review claim is present.

Phase 9b — implementer draft and incubation (blocked on external evidence)

Meet the implementer-draft gate in docs/STANDARDS-ROADMAP.md, including a general-purpose externally maintained implementation, requirement-to-test traceability, legal review of specification and patent terms and organizational supporters. Venue selection follows the resulting scope: W3C for Web and design-tool incubation, Khronos for graphics/content-tool conformance, or OASIS for a governed document protocol. Application alpha versions do not advance this phase.

Phase 10 — source-backed browser capture (active; local live segment automated)

Create a dedicated browser-capture adapter instead of expanding the retentive Tree-sitter adapter into a runtime. Pin browser/protocol/OS/context and collect bounded source, DOM/layout/style, downloaded-resource, font-use, accessibility and screenshot observations. Exit: repeated normalized observations/resource hashes reproduce; multi-viewport evidence predicts a held-out context; canvas, video, cross-origin and local-font gaps remain explicit; secret canaries never enter exported evidence. cargo xtask capture-baselines proves repeatable normalization, exact resource retention, query-secret redaction, typed proposal application and cycle rejection from fixed provider input. cargo xtask gate-j-live additionally drives exact Chrome for Testing 152.0.7977.64 with at most three recorded fresh-profile attempts per viewport. It records a structured runtime context, retains exactly the five declared response bodies, observes actual downloaded-font and accessibility results, repeats 360 px bytes exactly, excludes exercised query, cookie, storage, authorization and custom-header canaries, and beats the 360 px freeform geometry at held-out 900 px using the 360/768 px observations. The separate target/layout-inference-report.json ranks row stack, column stack, Grid, linear constraint and freeform alternatives without consulting the holdout, selects the constraint candidate, and records its 0.0626 normalized held-out error against 0.2918 for fixed freeform. This one fixture is an executable falsifier, not an accuracy distribution or proof of authored intent. Cross-OS/browser reproduction, opaque and cross-origin fixtures, complete matched-style/source correlation, canvas/video frame handling and real licensed pages remain open, so the broader phase does not yet exit.

Phase 11 — screenshot reconstruction baseline (active contract baseline)

Implement the vendor/model-neutral observation and typed-operation boundary from RFC 0011/specification 14. Compare deterministic OCR/CV, one-shot proposal, observation-assisted proposal, hierarchical crops, multi-viewport ranking and a bounded render/difference correction loop. Exit: one harness reports validity, text, element, tree, geometry, resources, held-out layout, provenance, visual, confidence, latency and memory/cost; flat screenshot copies fail the editable profile; an independent evaluator reproduces the main result.

The executable baseline currently proves observation-codec fixpoints, explicit observed/inferred evidence and omissions, typed atomic proposals, default flat-copy rejection, deterministic loop termination and training-only ranking of five bounded layout hypotheses against a live held-out viewport. The correction loop now has explicit success, no_improvement, and repeated_state outcomes, with a caller-provided objective threshold so a perfect score is never assumed by the core. The typed nuif-reconstruction-evaluation-0 report now covers every required per-example family, preserves empty denominators as unscored, rejects screenshot-only source-resource recall claims and keeps unavailable hardware measurements explicit. Its deterministic synthetic fixture validates the evaluator contract, not reconstruction quality. The missing OCR/model baselines, licensed real held-out corpus, independently reviewed group/near-duplicate assignments, predeclared FLIP thresholds/viewing contexts, statistical uncertainty method and independent evaluator keep the phase open. The pinned test-only LDR-FLIP implementation proves that exact and perceptual diagnostics can coexist and refuses implicit alpha handling; its one synthetic local error is not threshold calibration. A deterministic three-example fixture exercises typed distribution aggregation, including micro/macro separation and explicit missingness, without presenting it as empirical accuracy evidence. The typed corpus manifest and audit now pin snapshot/card/evaluator/artifact digests, separate disclosure and allowed-use policy, and reject exact or family-level leakage across all four partitions. Its four synthetic policy records prove the auditor, not the existence, legality, coverage or independence of a real corpus. The provider-manifest gate now binds every browser, screenshot, OCR, proposal and correction identity to canonical manifest bytes, requires that observation bundles carry the complete bounded registry and rejects dangling proposal identities before mutation. Released/learned fixtures require external SPDX 3.0.1 or CycloneDX 1.7 inventory identity, and learned fixtures require a model card. Synthetic digests and source-bundle development providers prove the contract only; no released model or accuracy result exists.

Phase 12 — calibration and conditional adaptation (calibration primitive active; adaptation blocked on Phase 11)

Calibrate decision-level confidence and establish review/abstain risk thresholds on disjoint data. Only if a stable learnable error distribution remains, create rights-cleared validated operation traces and compare prompt/tool changes, retrieval, supervised tuning, LoRA, QLoRA where compatible and sequence-level distillation. Exit: a candidate beats the untuned closed-loop baseline under the same frozen holdout/budget without validity, calibration, privacy, licensing or maintenance regression. Training is skipped if that gate is not met.

The current interpolation/selective-review fixture and cargo xtask confidence-calibration smoke test exercise only typed evaluator arithmetic, disjoint split enforcement, shifted holdouts and selective-review policy. They are not evidence of calibrated risk coverage on real data or of a production threshold.

Early falsifiers

Stop/rethink if: semantic model requires pervasive vendor-specific exceptions; opaque extensions cannot survive common operations; source synchronization routinely requires whole-file regeneration; independent implementation cannot reproduce normative layout/visual behavior from the spec; deterministic packages do not reproduce across writers; reconstruction optimizes pixels by discarding semantics; or tuning cannot beat the untuned tool-assisted baseline fairly.

Canonical source.

Standards-development roadmap

NUIF remains a pre-standard research project with a draft specification and reference implementation. The editor version 0.1.0-alpha.3 identifies an application prerelease. It does not establish specification stability, interoperability, resource-package conformance, reconstruction accuracy or external review.

Current publication boundary

The repository can publish source, generated documentation, schemas, conformance fixtures, implementation reports and a citable technical manuscript without joining a standards body. This stage uses the project code licenses and current contribution process. It does not create specification-wide patent commitments.

The following work is executable without external approval:

• publish the default-branch documentation through GitHub Pages;
• publish tagged source and native editor prereleases through GitHub Releases;
• expose CITATION.cff through GitHub’s repository citation interface;
• compile a technical manuscript from the canonical whitepaper modules;
• validate schemas, frontmatter, links, adapter coverage and conformance reports in GitHub Actions;
• archive a later public release with Zenodo after its GitHub integration is enabled by an authorized organization account.

GitHub adds a repository citation control when CITATION.cff exists on the default branch. Zenodo can ingest public GitHub releases after an account owner connects and enables the repository. Each release receives a DOI. Locators: GitHub Docs, “About CITATION files” and “Referencing and citing content”; Zenodo, “Enable a repository” and “Archive a release from GitHub”, retrieved 2026-08-30: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files, https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content, https://help.zenodo.org/docs/github/enable-repository/ and https://help.zenodo.org/docs/github/archive-software/github-upload/.

Implementer-draft gate

An implementer draft requires all of the following evidence:

• one bounded model and serialization profile whose normative requirements are internally consistent;
• a versioned schema and conformance suite mapped to every normative requirement;
• two independently maintained implementations that pass the same profile;
• at least one foreign-system round trip that preserves declared opaque data and reports every loss;
• security, privacy, accessibility and internationalization review records;
• a compatibility and deprecation policy for profile revisions;
• an extension namespace and registration process;
• specification copyright, patent, contribution and trademark terms reviewed by qualified counsel.

The present repository has an independent Python profile-zero evaluator and ten executable adapter profiles, including a normalized Figma mapping and compiled no-network review shell that explicitly exclude live host behavior, plus bounded three-engine web-accessibility and finite web-behavior projections. The behavior program also has one deterministic content-addressed package transport with an independent ZIP reader; it remains outside the canonical semantic document and is not a second complete implementation. These results cover bounded subsets. They do not constitute two independent implementations of the complete draft.

RFCs 0010, 0011 and 0012 are proposed research inputs. Their package, resource, behavior-attachment, capture and reconstruction profiles are not prerequisites for a small core implementer draft unless the selected charter includes them. If included, each requires its own independent implementation/evaluator report; a model demo or editor alpha does not satisfy interoperability.

Incubation gate

Standards-body incubation begins only after the implementer-draft gate and evidence of external participation. Venue selection follows the demonstrated adoption surface.

W3C Community Group reports are not W3C Standards. Khronos detailed Working Group design requires membership. Ecma and OASIS formal paths require member or sponsor governance. These conditions are process boundaries rather than technical quality rankings. Primary locators are recorded in research/items/standards-development-venue-comparison.md.

Formal-advancement gate

Formal advancement requires a stable chartered scope, recorded consensus, public review, resolved intellectual-property terms, interoperable implementations and conformance results. The selected body defines the exact ballot, review and patent procedures. NUIF cannot claim accreditation before that process completes.

The corresponding repository evidence includes:

• immutable specification snapshots and versioned conformance profiles;
• implementation reports linked to exact source revisions;
• test-suite coverage for every normative requirement;
• issue dispositions for security, privacy, accessibility and internationalization reviews;
• a public list of implementers, exclusions and withdrawn participants;
• release and errata procedures that distinguish compatible corrections from new feature levels.

Vendor adoption

Figma, Affinity, Canva and other hosts can evaluate the draft without replacing their internal document models. API hosts map a declared NUIF profile through a supported plug-in or service boundary. Affinity currently uses a separately declared file-interchange trial because no stable public document API was found. The headless CLI and WASM binding remain the semantic test surfaces. Vendor- private state is either represented, preserved as declared opaque data or reported through structured fidelity diagnostics.

The current Figma mapping and static shell, the Affinity SVG bridge draft and the Canva Apps SDK draft describe feasible boundaries but do not include their required live vendor-runtime trials. A vendor adoption claim therefore requires a signed test fixture, host-version matrix, import/export or transaction report and maintainer outside the reference-core implementation. Canva marketplace approval and native NUIF Connect support are separate upstream outcomes. The integration boundary is specified in docs/HOST-INTEGRATION.md and ADRs 0008 and 0012.

Decision authority

Technical evidence can identify a preferred venue and automate every repository-side prerequisite. It cannot accept patent obligations, sign a contributor agreement for another entity, create independent implementations or record stakeholder consensus. Those acts remain attributable to their human or organizational participants.

Canonical source.

Contributing

NUIF accepts research, specification, conformance, implementation and adapter contributions.

Research contributions

Add a stable research record under research/items/ using the repository schema. Prefer primary sources; include retrieval date, source version/commit where available, confidence, claims and explicit graph relationships. Do not silently replace conflicting evidence.

Specification contributions

Use an RFC for semantic/protocol changes. Every new normative behavior should include or identify a conformance fixture. Vendor-specific behavior belongs in an adapter or extension unless it demonstrates a broadly portable primitive.

Code contributions

Keep the Rust workspace formatted and warning-free. Core crates must remain independent of editor UI and vendor adapters. New parsing/rendering paths must document untrusted-input/resource-limit considerations.

Writing register

All persisted prose (documents, specification, research records, comments) uses the technical register defined in .claude/skills/research-register/SKILL.md: established terminology from the source field, no marketing language, no invented names for known concepts, a locator for every non-obvious claim. The glossary in .claude/skills/research-register/references/terminology.md lists preferred terms.

Commits

A commit message is exactly one line: <type>: <subject> with type in docs, research, spec, rfc, adr, feat, fix, test, refactor, perf, build, ci, chore; imperative mood; lower-case first letter; no trailing period; at most 72 characters. No body, no trailers and no attribution of tools, models or assistants. Enable the local hook with git config core.hooksPath .githooks; CI runs the same check (tools/git/commit-lint.sh).

Run tools/research/validate.sh after editing research/.

Canonical source.

Governance

NUIF is currently an experimental Refpath-hosted open research project, not an accredited standard.

Maturity surfaces

• The reference editor is a research preview. Its 0.1.0-alpha.N application version does not version the draft specification.
• The specification is pre-draft. No conformance profile is published as normative.
• Executable adapter profiles are experimental and apply only to their declared subset and evaluation matrix.
• A tag freezes one research instrument revision; it does not certify the architectural thesis or vendor interoperability.

Decision surfaces

• Research records collect evidence and may contradict one another.
• RFCs propose normative model/protocol changes.
• ADRs select reference-implementation techniques and do not automatically define the draft specification.
• Specifications become normative only when their status explicitly says so.
• Conformance fixtures are the executable interpretation of normative requirements.

Change process

Semantic changes require an RFC with motivation, alternatives, compatibility/loss analysis, security considerations, conformance changes and evidence links. Implementation-only changes may use an ADR when they establish a durable architectural choice.

Neutrality

Figma, Penpot, HTML/CSS, Svelte, React, Flutter, SwiftUI, Compose and future systems are adapters/implementers, not privileged sources of truth.

The long-term goal is neutral stewardship once the project has an executable stable profile and at least two independent implementations.

Pre-standard boundary

Standards-track publication requires an operative specification license, royalty-free patent commitments, contribution terms, named editor and maintainer roles, consensus and appeal procedures, a conflict-of-interest and antitrust policy, trademark rules and conformance-mark governance. The current MIT and Apache-2.0 terms license reference code; they do not establish those specification-development terms.

Canonical source.

Security policy

NUIF treats documents, assets, extensions and adapter inputs as untrusted. Binary and text decoders, archive decompression, fonts, images, vector paths, shader and effect extensions, GPU allocations and collaboration inputs are security-sensitive surfaces. The normative threat model is spec/11-security.md.

Supported releases

NUIF has no stable release. The latest editor prerelease receives security corrections when a report affects its declared profile. Earlier prereleases and unpublished source revisions do not receive a separate support period. This policy does not change the experimental status of the draft specification or its conformance profiles.

Private reporting

Report a suspected vulnerability through GitHub private vulnerability reporting. Include the affected revision or release, input profile, reproduction steps, observed result and expected boundary. Attach a minimized input when disclosure of that input does not create additional risk.

Do not publish exploitable parser, renderer, installer or updater details in a public issue before a coordinated correction is available. Non-sensitive bugs and already-public dependency advisories may use the public issue tracker.

Maintainers triage reports in the private advisory, determine the affected profiles and releases, prepare regression coverage and coordinate disclosure with the reporter. A correction is not complete until its hostile-input or regression case is exercised by the repository harness. Credit is recorded when requested and when disclosure does not expose private information.

GitHub documents the private reporting and advisory workflow in Privately reporting a security vulnerability, retrieved 2026-08-30: https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/privately-reporting-a-security-vulnerability.

Canonical source.

Code of conduct

Contributors are expected to keep technical discussion professional, evidence-based and focused on the work. Harassment, threats, discrimination and deliberate disruption are not acceptable.

Disagreement over architecture, standards evidence or implementation choices is expected. Critique claims and code directly; do not turn technical disagreement into personal attacks.

Maintainers may moderate or remove participation that repeatedly violates these expectations.

Canonical source.

Documentation publication

Repository Markdown is the sole editable documentation source. Files remain beside the implementation, specification module, decision or research record that they describe. docs/catalog.json defines site membership and navigation without copying document bodies.

Local commands

The documentation compiler is part of xtask:

cargo xtask docs-check
cargo xtask docs-build
cargo xtask docs-serve
cargo xtask docs-paper

docs-check validates catalog paths, unique document identifiers, required frontmatter, file budgets and relative links. Every repository Markdown source must be published or named in the catalog’s explicit exclusion list, so a new document cannot silently disappear from the site. The command writes the machine-readable catalog and report under target/. docs-build stages Markdown with generated navigation and invokes mdBook 0.5.4. The static site is written to target/docs-site. docs-serve rebuilds the staging tree and starts the local mdBook server. docs-paper builds the site and prints the generated technical manuscript to target/docs-site/downloads/nuif-research-manuscript.pdf through the repository’s pinned Chrome for Testing binary.

docs-paper keeps Chrome’s process sandbox enabled by default. A disposable, externally isolated CI runner that cannot create Chrome’s Linux namespace may set NUIF_CHROME_NO_SANDBOX=1; do not use that override for routine local rendering.

The pinned renderer can be installed through:

cargo xtask docs-setup
cargo xtask browser-install

Generated navigation, search indexes and HTML are build artifacts. They are not committed.

The manuscript body is generated from the whitepaper modules listed in docs/catalog.json. The composition metadata does not copy chapter text. Publication does not imply peer review or specification maturity.

Metadata boundary

Specification modules, RFCs, ADRs and research records require YAML frontmatter. docs/schema/document.schema.json defines the common identifier, kind and status fields. Research records retain their additional schema in research/schema/research-item.schema.json.

The compiler accepts a maximum of 2 MiB per Markdown file and 64 KiB per frontmatter block. It uses typed YAML deserialization with duplicate-key rejection and parser resource budgets. YAML metadata does not define the NUIF interchange syntax.

Hosted publication

The Pages workflow builds the same staged source on pull requests and on the default branch. Pull requests retain a build artifact and do not deploy. A default-branch build uploads target/docs-site as the GitHub Pages artifact and deploys through the github-pages environment. GitHub documents custom Actions workflows for generators other than Jekyll and for repositories that do not want compiled output on a publication branch. Locator: GitHub Docs, “Configuring a publishing source for your GitHub Pages site”, “Publishing with a custom GitHub Actions workflow”, retrieved 2026-08-30: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site.

The workflow pins every action to a full commit. It grants read-only repository contents to the build job. Only the deployment job receives pages: write and id-token: write; it does not receive source or release write permission.

GitHub Wiki is not a publication target. GitHub stores each wiki in a separate Git repository, so enabling direct edits would create a second source history. GitHub also documents restricted search-engine indexing for wiki content and recommends GitHub Pages for public documentation. Locator: GitHub Docs, “Adding or editing wiki pages” and “About wikis”, retrieved 2026-08-30: https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages and https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis.

GitBook bidirectional synchronization is not enabled. Its Git Sync can modify SUMMARY.md and synchronize edits from GitBook to the connected branch. That mode would add another authoring surface. Locator: GitBook documentation, “Git Sync” and “Configuration”, retrieved 2026-08-30: https://gitbook.com/docs/getting-started/git-sync and https://gitbook.com/docs/getting-started/git-sync/content-configuration.

Immutable records

The Pages site represents the default branch and is not an immutable specification release. Git tags, release notes and source archives remain the versioned record. A later citable research release can add CITATION.cff, a Zenodo concept DOI and a version DOI without changing the canonical Markdown source. Publication prerequisites and venue constraints are recorded in research/items/scholarly-publication-and-citation-workflow.md.

Canonical source.

Host integration and vendor adoption

Figma and Canva use NUIF through small host adapters, not by embedding the native NUIF editor. Affinity is currently a file-interchange and foreign-runtime target because no stable public Affinity document-object or scripting API was located in the reviewed official material. In every case the product continues to own its canvas, document and undo lifecycle. NUIF maps only a declared profile and emits evidence describing what was exact, approximated, preserved or unsupported.

The architectural decision is ADR 0008; ADR 0012 sets the current vendor priority and evidence boundaries. Primary evidence is recorded in nuif:research:figma-plugin-and-rest-api-as-automation-surface and nuif:research:affinity-interchange-and-adoption and nuif:research:canva-apps-and-connect-adoption.

Deliverables for a host

A production host integration consists of five independently reviewable parts:

1. A bounded profile that lists mapped host object kinds and properties, resource limits, unsupported semantics and identity rules.
2. Pure import/export mapping functions covered by checked-in host snapshots and expected canonical NUIF documents.
3. For API hosts, a thin plug-in shell for file selection, host permission prompts, undo and user-visible fidelity confirmation. For interchange-only hosts, a documented user-mediated trial and exact input/output artifact set.
4. A nuif-adapter::HostAdapterReport for every direction. The report records the host/API version and revision, canonical hash, host-object correspondences, property fidelity and preservation result.
5. A host-specific package or interchange kit, version stream and release gate. These artifacts do not inherit the native editor’s version.

The portable contract is canonical NUIF plus the report. Rust is optional for a vendor implementation. A TypeScript or JavaScript plug-in may implement the same mapping directly from the specification and conformance fixtures.

Rust hosts use the package-aware nuif-api::NuifDocument façade documented in docs/SDK-AND-BINDINGS.md. Browser plug-ins use the thin WASM wrapper over that façade. A stable C/Swift/Kotlin ABI is deliberately not claimed during the 0.0.x semantic-API phase; ADR 0011 defines the native-binding promotion gate.

Browser binding boundary

nuif-wasm-api-0 packages parsing, validation, canonical text/CBOR, deterministic .nuif load/export, explicit manifest-capability negotiation and bounded semantic patch/history operations for browser and JavaScript consumers. It retains verified embedded resources without exposing a second mutable JavaScript model. The generated module has no filesystem, network, Figma, Canva or Affinity authority.

For Figma, the module belongs in the UI iframe, where Figma documents normal browser APIs including WebAssembly. The plug-in main thread still owns SceneNode access and exchanges bounded messages with that iframe. Canva apps also run in an iframe; Canva’s current content-security policy admits packaged WebAssembly while blocking third-party scripts, nested frames and workers. A Canva build must therefore bundle the NUIF module with the reviewed app and let the Apps SDK own every design mutation. Affinity has no equivalent documented embedding boundary, so its first profile invokes the existing SVG adapter outside the product and uses user-mediated import/export. The WASM module can validate, edit and re-encode complete NUIF packages locally, but it is not a host adapter and cannot justify a vendor fidelity claim by itself.

Local package evaluation

A Rust host that opens a package passes only its verified embedded resources to the in-process session:

#![allow(unused)]
fn main() {
let package = NuifPackage::decode(bytes)?;
package.require_capabilities(&host_capabilities)?;
let session = Session::with_resources(
    package.document.clone(),
    package.embedded_resources(),
)?;
let snapshot = session.snapshot(&context)?;
}

Inspection or extraction tools may instead call capability_report and retain unknown required resources without claiming full support. Structural decode never executes a capability and does not authorize a semantic rewrite: a tool must negotiate the complete set or explicitly detach the package before migration. A rendering or behavior host must pass the exact declared supported set before it presents the package as fully evaluated.

Session::with_resources rechecks every SHA-256 binding and enforces count, single-resource and total-byte limits before it can render. It grants no linked resource or network authority. Package/session handoff shares immutable byte buffers, so cloning a package or opening a render session does not duplicate the complete embedded-resource payload. The CLI and reference editor use this path, so opening a package containing a nuif-png-rgba8-0 or nuif-png-basic-rgba8-1 image resolves it locally; a bare document or unresolved link continues to emit item-level fidelity. Hosts that need authenticated or remote resources keep that policy outside the session, resolve explicitly, verify against the descriptor, and then create a new bounded session.

The release allocation trial hands an 8 MiB embedded buffer from package to session with the same allocation pointer; map/session construction allocates under 1 MiB and retains under 1 MiB. Scene lowering separately stores one decoded surface for repeated image uses and enforces a 64 MiB unique decoded surface total before inflation. These are regression ceilings measured by cargo xtask gate-i-package and cargo xtask gate-i-image, not promises about an arbitrary host allocator.

Figma path

The executable pure-mapping profile is adapters/figma/SNAPSHOT-PROFILE.md; the live-host promotion contract remains adapters/figma/PROFILE-DRAFT.md.

Figma Plugin main thread
  ├─ reads/writes current PageNode and SceneNode objects
  ├─ owns host mutation and undo grouping
  └─ exchanges typed messages with
       Figma UI iframe
         ├─ user selects or downloads .nuif/report files
         └─ parses/serializes the bounded profile

nuif-figma implements the normalized JSON boundary between those two threads. It maps one visible, opaque, fixed-size frame subtree to canonical NUIF and produces a deterministic mutation-plan tree in the other direction. adapters/figma/plugin compiles the thin main-thread and iframe shell against the pinned official typings. The release-mode gate covers exact round trips, identity repair, unsupported-property evidence, hostile bounds, static message validation, a no-network bundle and a TypeScript fixture imported by Rust. It does not execute figma.create*, font loading, page loading, undo or plug-in messaging in Figma; those remain live-host promotion evidence.

The manifest template targets only figma, requires dynamic page loading and declares no network domains. Figma assigns the required plug-in ID; a reviewer passes that assigned value at packaging time, and CI never substitutes a fake ID. The shell only reads the selected subtree on the current page. Import validates a precomputed plan, stays disabled until confirmation, removes nodes created by a failed attempt and commits success as one undo step. Export does not mutate the file.

Host node IDs are recorded in correspondence evidence. A shared nuif plug-in-data namespace may carry document/entity identifiers for synchronization, subject to the 100 kB entry limit. Because Figma does not document every copy/duplicate persistence case, the bridge must scan imported identifiers, replace duplicates and report the repair. A changed plug-in ID must not be used as the only identity store because private plug-in data becomes inaccessible under another ID.

The REST API is suitable for authenticated read snapshots and server-side validation, not the primary write path. The writable path is the user-run Plugin API. Dev Mode plug-ins are read-only and are not the import target.

Affinity path

The first Affinity contract is adapters/affinity/PROFILE-DRAFT.md. The all-new Affinity combines vector, photo and page-layout tools in one no-cost desktop product, which makes live interchange trials accessible to contributors. That product position is useful evidence for adoption priority; it does not create a public plug-in API or disclose the native .af, .afdesign, .afphoto or .afpub encodings.

Profile 0 is consequently a user-mediated SVG bridge:

canonical NUIF
  -> nuif-svg-0 export + fidelity report
  -> user imports SVG into a named Affinity version
  -> user exports SVG
  -> nuif-svg-0 import + host trial report

The bridge accepts only the existing nuif-svg-0 basic-shape and pinned-text subset. An Affinity-exported SVG containing paths, transforms, effects, CSS, external resources or other excluded SVG features is rejected or reported as unsupported; it is never silently simplified. Native Affinity files remain opaque evidence artifacts. Canva’s Connect API accepting Affinity file extensions proves a supported Canva ingestion route, not that their schema is public or suitable for a NUIF parser.

No headless automation, stable identity persistence, undo integration or exact native round trip is claimed. Promotion requires named desktop versions on each supported operating system, retained input/output files, screenshots or renders, a complete fidelity report and a second-person review. A future public Affinity scripting or document API would justify a separately versioned host profile; undocumented UI automation and native-format reverse engineering do not.

Canva path

The first programmable profile is adapters/canva/PROFILE-DRAFT.md and uses the stable Apps SDK Design Editing API. It is deliberately limited to one unlocked, fixed-dimension current_page session and the supported group, rect, shape and rich-text element kinds. Images are media fills on rectangles in the Canva model. Canva Docs, unbounded pages, tables, embeds, video, unsupported elements, unavailable fonts and preview-only APIs are outside profile 0.

The app reads the page snapshot, translates it through a bounded normalized schema, validates the complete candidate and then calls sync once. This makes one confirmed NUIF import one host undo action and avoids partial mutation. Sessions expire after one minute, locked pages and elements remain untouched, and every unsupported property appears in the host report. The app never replaces the entire design with an opaque app element or raster screenshot.

Canva Connect APIs are a secondary off-platform workflow. They support OAuth imports of listed foreign formats and asynchronous exports to formats such as PDF, PNG, JPG, PPTX, GIF, MP4, CSV and HTML. The current import list includes Affinity files but not NUIF. Therefore SVG/PDF may be used as explicitly lossy bridges, while exact NUIF import/export requires either the Apps SDK mapping or future native application/nuif+zip support from Canva. Connect download URLs are temporary and API scopes, rate limits, user authorization and server-side privacy obligations remain outside the core.

The first public app uses only generally available APIs. Canva documents that preview APIs may change without versioning and prevent public review. CI can build and test a source bundle, but a public release still requires developer verification, source upload, listing and testing material, Canva review, and an explicit owner-triggered release. A team app is not the default open-source distribution path because Canva limits team apps to Enterprise teams.

Conformance gate

A host profile becomes integrated in adapters/index.json only when all of these pass:

• checked-in host input and expected canonical NUIF output;
• exact repeated import/export results for the declared subset;
• a valid host report with non-empty host/API/profile identity;
• one fidelity entry for every mapped or excluded authored property;
• stable correspondence after reorder and reopen where the host supports it;
• duplicate/missing identity repair cases;
• maximum and limit-plus-one document, node, text and metadata inputs;
• cancellation and atomic-failure tests that leave the active host document unchanged;
• one native-host trial recording product version and package version.

Credential-free CI tests mapping functions, the compiled shell and snapshots. Live-host CI or manual certification supplies the final product/version evidence. Passing static shell tests does not justify a live integration claim.

Release operation

The native editor, nuif-wasm developer binding, Figma review shell, Affinity interchange kit and Canva app are versioned independently. CI should build review bundles, checksums, provenance, an SBOM where applicable and fixture reports. Publication to a vendor marketplace is never inferred from a Git tag: it requires the vendor account, assigned app identifier, identity and legal disclosures, review forms, and an explicit authenticated release operation.

Canonical source.

SDK and language-binding boundary

nuif-api is the ergonomic in-process SDK over the authoritative model, codecs, package, operation, layout and render crates. It is intentionally a façade rather than another implementation. The CLI, reference editor, WebAssembly module and MCP adapter translate their environment at the edge and delegate semantic work to this layer.

                         nuif-api::NuifDocument
                      load · validate · apply · export
                                   │
                 canonical codecs · package · operations
                                   │
                  model · layout · render · diagnostics
                     ┌─────────────┼─────────────┐
                  native         WASM          process
                 Rust host    browser/plugin   CLI/MCP

Direct Rust use

Bare encodings are explicit; the SDK does not guess from an arbitrary byte prefix. Package loading is a separate call because it structurally validates the ZIP, manifest, document, resource descriptors, embedded bytes and policy before a session is returned. Host support is negotiated after structural decode or atomically through load_package_with_capabilities.

#![allow(unused)]
fn main() {
use nuif_api::{DocumentEncoding, NuifDocument};
use nuif_package::PackageMode;

let mut document = NuifDocument::load(bytes, DocumentEncoding::CanonicalText)?;
let report = document.validate()?;
let patch = document.apply_operations(transaction_id, operations)?;
let revision = document.canonical_hash()?;
let cbor = document.export(DocumentEncoding::DeterministicCbor)?;
let package = document.export_package(PackageMode::Portable)?;
}

load_package retains verified descriptors and shared immutable embedded bytes. When the manifest has requirements, its session is structural and read-only: validation, hashing, bare extraction and an unchanged same-mode package copy remain available, while semantic mutation, undo/redo, evaluation and mode conversion return the exact required set. Successful negotiation authorizes those actions for that loaded session. export_package then replaces only the package’s semantic document and requested mode and runs the ordinary package policy; it cannot silently fetch linked resources. Applying operations uses the same atomic transaction, revision and undo/redo implementation as the editor.

#![allow(unused)]
fn main() {
let mut structural = NuifDocument::load_package(package_bytes)?;
let report = structural.package_capability_report(&host_capabilities);
structural.require_package_capabilities(&host_capabilities)?;

let supported = NuifDocument::load_package_with_capabilities(
    package_bytes,
    &host_capabilities,
)?;
}

The report contains required, supported-required and missing-required sets in deterministic order. Extra host capabilities are ignored. Structural loading is appropriate for inert inspection, preservation and an explicit bare extraction before migration; it is not authorization to rewrite the package or a claim that the host can evaluate every required profile.

Structurally invalid but syntactically decodable bare documents can be loaded for diagnostics; canonical export, hashing, layout and rendering still fail closed. Package inputs are structurally valid or rejected atomically; full package support additionally requires explicit capability negotiation.

Binding rule

Wrappers contain transport and ownership conversion only:

• WebAssembly accepts byte arrays, bounds JSON patch and capability-set transport, and delegates bare/package loading, validation, hashing, capability negotiation, canonical export and history to NuifDocument.
• MCP bounds newline-delimited protocol messages and maps stateless tool calls to the same API.
• The CLI owns files and stdout; the editor owns window and interaction state.
• The CLI declares an empty package-capability support set. It may inspect, validate, hash, extract or copy a capability-bearing package, but rejects layout, render, snapshot, external-format export, changed package saves and package-mode conversion with PACKAGE_CAPABILITIES_REQUIRED.
• The reference editor opens unsupported capability-bearing packages only for structural read-only inspection and exact copying; it rejects semantic edits at both the session and package-save boundaries.
• A host plug-in owns vendor objects, permissions and undo grouping. WASM does not become the Figma or Canva adapter merely because it runs in a plug-in; Affinity currently has no documented plug-in boundary for this project and uses a user-mediated interchange profile instead.

The cross-surface rule is exact: the same input and patch must produce the same canonical hash, canonical bytes and diagnostics. For package-aware surfaces it also requires the same deterministic archive bytes, retained resources and missing-capability set. cargo xtask gate-wasm and cargo xtask gate-mcp compare wrappers with native output; the Criterion sdk/direct_document group measures direct text, CBOR and package loading plus canonical export.

C, C++, Swift and Kotlin decision

No stable foreign ABI is declared during the 0.0.x semantic-API phase. Rust’s native ABI has no stability guarantee. A C-compatible ABI is possible, but it adds an unsafe ownership boundary whose handle lifetime, buffer allocation and release, panic containment, error representation, thread rules, symbol set and calling convention become a compatibility promise independent of Rust source compatibility. Generating a header does not decide those rules.

The promotion path is:

1. Freeze a byte-oriented nuif-ffi-1 contract over NuifDocument, not over internal model structs.
2. Put all unsafe code in a separately reviewed nuif-ffi crate; keep the model, codec, operation and SDK crates under unsafe_code = "forbid".
3. Catch panics before the ABI boundary, return stable numeric error classes plus owned diagnostic bytes, and provide one allocator-matched buffer-free function and one idempotent handle-free function.
4. Generate C and C++ headers with a pinned cbindgen release, diff the exported symbol/header surface in CI and run C consumers under sanitizers on every supported target.
5. Generate Swift and Kotlin wrappers with a pinned UniFFI release after its generated ownership/checksum behavior passes native tests. Package an XCFramework/Swift package and Android AAR separately; UniFFI generates bindings but does not ship those platform artifacts.
6. Apply semantic-version and ABI-compatibility checks to the FFI profile independently from the editor, WASM and MCP versions.

Promotion requires a reviewed error-code registry, a declared threading model, an API compatibility baseline, consumer fixtures in C/Swift/Kotlin, sanitizer evidence and release packages for their actual target triples. Until then, Swift or Kotlin desktop/mobile experiments should use the WASM package where their host embeds an appropriate runtime, or call a local CLI/process adapter; neither path is described as a native production binding.

For Node.js the WebAssembly package remains the default because it already has exact native parity and no native addon installation matrix. A Node-API addon is justified only if the benchmark suite shows a material workload that WASM cannot meet. The WebAssembly Component Model remains a possible future plug-in ABI, not a substitute for the currently deployed browser module.

Release boundary

The editor, CLI, WASM binding, MCP service and eventual FFI packages have independent versions. A tag for the editor may attach tested developer artifacts, but it does not promote nuif-api or promise a stable ABI. The CLI archive is the explicit no-store process integration for automation that does not need MCP; its package smoke report exercises real generation, validation, canonicalization and inspection through the release binary. Publishing a crate, npm package, Swift package, AAR or vendor plug-in requires an explicit policy and authenticated release operation for that ecosystem.

Canonical source.

Diagnostic code registry

This is the canonical public registry for structured profile-zero diagnostics emitted through nuif_core::Diagnostic and for failure codes retained by the reference conformance trial. Automation must branch on code, not on the human-readable message. Messages may gain detail without changing a code.

The severity below is the default for the owning profile. A code is never repurposed; a materially different condition receives a new code. Adding a code is compatible within an alpha profile, while removing a code or changing its meaning requires a profile-version decision. entity, pointer and fidelity remain the attribution fields defined by the diagnostic record.

Transport and command failures such as malformed CLI arguments, unavailable package capabilities and WASM input limits are error classes rather than document diagnostics. Their promotion boundary is tracked separately in SDK and language-binding boundary.

cargo xtask diagnostic-audit compares this bytewise-sorted table with every code literal owned by model validation, layout evaluation and the conformance trial. It writes target/diagnostic-registry-report.json and fails when a code is undocumented, duplicated, stale, malformed or out of order.

Canonical source.

Versioning and release operation

The native editor uses Semantic Versioning independently from the draft specification profiles and unpublished library crates. The first editor release is 0.1.0-alpha.1; the corresponding Git tag is v0.1.0-alpha.1. The decision and source evidence are recorded in ADR 0007 and nuif:research:github-release-delivery-and-provenance.

Version contract

• apps/editor/Cargo.toml contains the editor version.
• A release tag equals v followed by the exact editor version.
• Prerelease corrections increment the numeric suffix. A published tag is not moved or reused.
• The draft specification’s profile-zero identifier is not an application version and does not change when the editor prerelease increments.
• Editor alpha maturity does not transfer to proposed package, resource, capture, reconstruction or model artifacts. Each of those requires its own profile identifier, conformance evidence and release record.
• Library crate versions remain independent until a crate publication policy is adopted.
• nuif-api is the direct Rust SDK façade during this policy-free 0.0.x phase; its source API is usable from a reviewed checkout but no stable Rust or C ABI is promised. The FFI promotion gate is defined in ADR 0011 and docs/SDK-AND-BINDINGS.md.

Release sequence

1. Update the editor version and docs/releases/<version>.md in one reviewed commit.
2. Run cargo xtask all, the native editor tests, cargo deny check, and cargo xtask editor-package on a clean tree.
3. Create and push the exact version tag.
4. .github/workflows/release.yml checks out the tag and runs cargo xtask release-check <tag> followed by the complete verification harness.
5. Native jobs build, test, package, and attest five editor host architectures; a separate job builds, cross-checks, packages and attests the browser binding, and two five-host matrices do the same for the MCP service and standalone CLI developer binaries.
6. The publication job writes checksums and a combined release manifest, creates a draft release, uploads all assets, and publishes the prerelease.

The workflow can be rerun manually for an existing unpublished tag. It refuses to replace a published release. GitHub’s immutable-release setting is compatible with the draft-attach-publish sequence but remains a user-managed repository setting. Locator: ADR 0007; .github/workflows/release.yml; GitHub Immutable releases, retrieved 2026-08-30: https://docs.github.com/en/code-security/concepts/supply-chain-security/immutable-releases.

Artifact contract

Release archives use this form:

nuif-editor-<version>-<os>-<architecture>.<tar.gz|zip>

Each archive has a sibling .manifest.json. The release also contains SHA256SUMS, nuif-editor-<version>.cdx.json, and release-manifest.json. The CycloneDX document inventories the editor’s Cargo dependency graph for all release targets. GitHub provenance can be checked with:

gh attestation verify <archive> --repo refpath/nuif

Tagged prereleases also attach nuif-wasm-0.0.1-web.tar.gz and its .binding.json manifest as a separately versioned developer binding. The binding is listed under bindings in the release manifest and does not count among the five native editor packages used by the source updater. Its package.json is private: GitHub download is automated, npm publication is not authorized until an independent library-version policy is adopted.

The same prerelease attaches five nuif-mcp-0.0.1-<os>-<architecture> archives, sibling manifests and a separate nuif-mcp-0.0.1.cdx.json SBOM. These independently versioned developer-service records appear under services in the release manifest. Every host binary is exercised through the live stdio conformance gate before packaging. The crate remains unpublished; developers may either use an attested archive or build it from a reviewed checkout with cargo install --path crates/nuif-mcp --locked.

Five nuif-cli-0.0.1-<os>-<architecture> archives, sibling manifests and a separate CLI SBOM provide the no-store command-line path. Before packaging, each release binary reports its version and capabilities, creates the profile-0 fixture, validates and canonicalizes it, and inspects the canonical result. The records appear under tools in the release manifest. The CLI has only caller-selected path and standard-stream authority; it has no background service or implicit network access. Developers may instead build the same binary from a reviewed checkout with cargo install --path crates/nuif-cli --locked.

SHA-256 verification on Linux uses sha256sum -c SHA256SUMS. macOS uses shasum -a 256 -c SHA256SUMS. PowerShell users can compare Get-FileHash -Algorithm SHA256 with the corresponding line in SHA256SUMS.

Developer channel contract

Release archives are evidence and an expert opt-in path. The primary developer installation builds locally from a retained source checkout according to ADR 0009. source installs the current clean revision. alpha additionally requires the exact release tag and rejects a dirty tree.

An explicit editor-update --channel alpha operation queries published prereleases and selects the greatest numeric MAJOR.MINOR.PATCH-alpha.N version. It accepts a release only when release-manifest.json exists, its five package records passed from one clean source revision, and its GitHub attestation verifies the repository, release workflow, tag, source digest and GitHub-hosted runner. The updater fetches the attested tag with Git hooks disabled and requires the checked-out commit to equal that digest before building with Cargo.lock.

The lifecycle retains an active and previous immutable install. It never moves a release tag, installs from a mutable branch, performs a silent update or changes an operating-system trust policy. See apps/editor/INSTALLING.md for commands and paths.

Signing boundary

The alpha artifacts are unsigned and record that status in each manifest. Checksums and GitHub attestations verify bytes and build origin; they do not provide an operating-system publisher identity. Apple distribution requires a Developer ID signature, hardened runtime, timestamp, notarization, and ticket stapling. Windows direct distribution requires a trusted publisher signature for an identified publisher and reduced SmartScreen friction. Locator: nuif:research:github-release-delivery-and-provenance, Evidence.

Signing credentials are never stored in the repository. Adding a signing stage requires a separate review of identity ownership, secret storage, rotation, fork behavior, and release recovery.

Canonical source.

NUIF foundation

Document status: draft. Canonical source.

NUIF investigates a portable, vendor-neutral draft specification for authored user-interface documents. The candidate model is intended to preserve meaning across editors and implementation targets rather than treating a rendered bitmap, a vendor scene graph, or source-language AST as the universal truth.

Thesis

A useful portable interface specification must coordinate several representations instead of collapsing them into one:

1. semantic/document containment;
2. component and instance identity;
3. authored layout and responsive constraints;
4. resolved geometry at explicit evaluation contexts;
5. geometry, paint, typography, and assets;
6. design-token references and themes;
7. interaction/state and data-binding graphs;
8. source/tool provenance and correspondence;
9. extension payloads that can survive unknown intermediaries;
10. deterministic operations, diff, patch, and reconciliation.

Portable resources add a second identity boundary: editable semantic assets retain stable IDs, while exact image/font bytes use immutable content digests. Package paths and source URLs are locators/provenance, not identity.

NUIF therefore treats portability as a synchronization problem as much as a serialization problem.

Architectural hypothesis

The working model is a small canonical core plus coordinated graphs and extension dialects. The containment tree answers ownership and order. Typed relationship graphs express constraints, components, tokens, interactions, provenance, dependencies, and other relationships that do not belong in a tree.

The reference implementation will preserve both authored and resolved state. Resolved state is always scoped to an evaluation context and is never allowed to silently replace authored intent.

Fidelity model

Every adapter and transformation must classify material mappings:

• lossless — semantics are preserved exactly;
• representable — equivalent target semantics exist, even if encoded differently;
• approximated — a declared approximation is produced;
• preserved_unrenderable — data survives as an extension but the target cannot render/edit it;
• unsupported — data cannot currently be represented or preserved safely.

Silent loss is a conformance failure.

Explicit non-goals

NUIF does not promise to infer the unique original source program from pixels, reproduce arbitrary JavaScript execution, make every platform text renderer bit-identical, or force every target to support every capability. The draft specification should make such boundaries inspectable and machine-readable.

Screenshot reconstruction is therefore an optional inference client, not a new canonical truth. It may propose a validated editable hypothesis and calibrated alternatives, but screenshot-only evidence cannot be classified as lossless authored source.

Reference implementation role

The Rust implementation and editor are executable research instruments and conformance references. They do not define semantics by accident; normative behavior belongs in spec/ and must be testable independently.

NUIF architecture thesis

NUIF is a specification-first authored-interface model. Its center is neither a vendor editor nor a source framework.

Core thesis

A portable interface document must retain intent, structure, relationships and evaluated results simultaneously. A single flattened scene tree cannot preserve enough information for loss-minimizing round trips across editors and runtime frameworks.

The recommended architecture is a layered hybrid:

Document containment tree
        │ stable IDs
        ├── component / instance graph
        ├── token / theme graph
        ├── layout constraint graph
        ├── interaction / state graph
        ├── provenance / correspondence graph
        └── asset dependency graph

Authored model ──evaluate/lower──► resolved model ──► render scene
      ▲                               │
      └──────── reconcile / lift ◄────┘

Borrowed foundations

• MLIR: dialects, explicit lowering, partial legality and multiple abstraction levels.
• OpenUSD: non-destructive composition, references, layers and variants.
• glTF: small core, extension registry, used/required capabilities.
• DTCG: token interchange.
• SVG/Unicode/OpenType: geometry and text foundations.
• Retentive/symmetric lenses: synchronization with preserved source regions.

New work required

NUIF must define the missing combination: authored UI semantics + resolved state + cross-tool provenance + structural loss accounting + source patch synchronization.

Canonical layers

1. Document layer — identity, containment, semantics, accessibility.
2. Component layer — definitions, instances, slots, parameters, variants and overrides.
3. Layout layer — authored sizing/layout intent independent of resolved geometry.
4. Visual layer — geometry, paint, text and effects.
5. Behavior layer — interactions, states, animation and data bindings.
6. Resolved layer — computed layout, shaped text, flattened paint/effect plans for a declared evaluation context.
7. Provenance layer — source/destination correspondence and fidelity diagnostics.
8. Resource layer — stable semantic assets bound to content-addressed bytes, package/resolver locators and derivation records.

No lower layer is permitted to silently erase a higher-level authored construct. Lowerings that cannot represent a construct must emit fidelity records.

Stable identity

Identity is semantic and independent of path, order and display name. Moving an entity does not change its ID. Content hashes identify immutable resources and canonical snapshots, not editable semantic entities.

Compiler and reconstruction ports

Deterministic source adapters and probabilistic screenshot reconstruction meet at the operation boundary:

retained source + resolved host observations ─┐
                                              ├─> typed operations -> core
pixels + OCR/CV/model hypotheses ─────────────┘                    -> render/evaluate

Source-backed and screenshot-only inputs retain distinct evidence classes. A model/provider is replaceable and cannot redefine the operation grammar, validator, layout semantics, resource identity or fidelity ceilings.

Falsifiability

The architecture fails if the v0 experiment cannot preserve a non-trivial responsive component through editor→HTML→NUIF→editor while retaining component identity, token bindings, layout intent, an opaque foreign extension and a minimal source patch after an edit.

The resource/reconstruction extension fails if independent package writers cannot reproduce the proposed bytes, if browser capture cannot be pinned without secret leakage, if visual objectives reward flat screenshot copies, or if adaptation fails to beat the untuned tool-assisted baseline on a frozen holdout.

Canonical source.

Layout and rendering research synthesis

Layout is not geometry

NUIF separates authored constraints from resolved boxes. Fixed x/y/width/height are valid authored values for freeform content, but they are not the universal layout representation.

The initial layout vocabulary contains families rather than one universal algorithm:

• freeform — transforms/anchors and explicit geometry.
• stack — one-dimensional flow with intrinsic sizing, distribution, alignment and gaps.
• flex — web-compatible flexible layout semantics.
• grid — bounded explicit fixed/fr tracks, spans and deterministic no-implicit-track placement in profile 0; broader CSS Grid features remain capability-reported adapter input.
• constraint — relational linear constraints for editor/native-layout cases.
• custom — extension/dialect-defined evaluator with declared fallback/resolved geometry.

Common sizing primitives are normalized across families: fixed, intrinsic-min, intrinsic-max, fit-content, fill/available, percentage, min/max clamps, aspect ratio and content measurement.

Taffy is the recommended first evaluator for CSS-compatible block/flex/grid behavior because it implements web algorithms in Rust. SwiftUI’s proposal-response model and Cassowary-style constraints demonstrate why the canonical schema must remain a superset rather than serializing Taffy’s Style directly.

Evaluation context

Resolved layout is keyed by an explicit context including viewport/container size, pixel ratio, locale, writing direction, font set, token/theme selection and feature/dialect capabilities. Multiple resolved snapshots may coexist as caches or conformance fixtures.

Rendering semantics

The draft specification defines the visual meaning of paths, fills, strokes, transforms, clipping, masks, gradients, compositing, images, text and supported effects. It does not specify GPU command buffers or a renderer implementation.

The reference renderer uses a backend trait. Vello/wgpu is the leading interactive experiment, but conformance requires deterministic raster comparisons and must permit CPU reference rendering where GPU differences would make tests unstable.

Text

Canonical text remains Unicode text + style runs + semantic annotations + font references. Shaping produces resolved glyph IDs, clusters, advances and offsets using pinned font data and a declared Unicode/shaping version. A glyph cache never replaces semantic text.

Portability reports must distinguish font substitution, missing glyphs, line-break differences and rasterization differences from document-model loss.

Canonical source.

Protocol, portability and synchronization

NUIF treats portability as an ongoing synchronization problem.

Operations

The protocol operates on stable entities and semantic properties. Operations include create/delete/move, set/unset property, list/set relation edits, component/instance overrides, token bindings, extension edits and transactions. Editor gestures lower to these operations.

A drag inside a stack should usually become a reorder or layout-property edit; a drag in freeform space may become a transform edit. GUI coordinates are input data, not the protocol abstraction.

Patch model

A patch is a deterministic ordered set of operations with base snapshot identity, optional preconditions, transaction metadata and provenance. Patches can be replayed headlessly.

Three-way merge uses stable identity first and structural matching only when identity is absent. Conflicts are typed: property, delete/edit, ordering, relationship, extension and semantic-lowering conflicts.

Correspondence

Adapters maintain correspondence records between NUIF entities/properties and foreign constructs such as DOM nodes, CSS declarations, Svelte component props or design-tool node IDs. Correspondence is separable from the canonical design so source-specific metadata can be detached when unnecessary.

Fidelity classes

Every adapter/evaluator may report:

• lossless — semantics preserved and reconstructable.
• representable — equivalent semantics represented through different constructs.
• approximated — visible/behavioral approximation with known semantic loss.
• preserved_unrenderable — data retained opaquely but not understood/rendered.
• unsupported — data could not be safely preserved.

Silent degradation is a conformance failure.

Canonical source.

Serialization, collaboration and governance

Logical model before encoding

NUIF defines one logical model with multiple conforming encodings.

Text form

A canonical, reviewable representation is implemented for examples, fixtures, diffs and Git workflows. nuif-text-0 fixes number formatting, UTF-8 key order, layout and strict decode/canonicalize behavior; later text profiles may evolve only through explicit versioning.

Binary form

Deterministic CBOR is the profile-0 binary form because the NUIF profile closes the choices left by RFC 8949 without coupling the logical model to generated code. The executable codec gate finds it near 41% of canonical-text size at 4,096 entities on an Apple M5 Pro run, while its typed decode path is slower than text. That result supports CBOR as a compact canonical form, not as a universal latency winner.

A candidate is timed only after complete-model round trip, canonical fixpoint and unknown-data preservation through a neighboring edit. Protobuf does not specify canonical binary output. FlatBuffers deliberately permits different byte layouts and old readers ignore new fields, so a rebuilding editor needs a separate retention strategy. Cap’n Proto specifies a schema-agnostic canonical form and is the preferred next experiment, but it still needs a complete NUIF mapping, bounded old-reader edit trial and two agreeing canonical writers. Compiled zero-copy runtime caches remain separate, explicitly noncanonical profiles rather than replacements for authoring interchange.

The experimental package form separates manifest/document records from content-addressed resources. RFC 0010 selects a candidate deterministic ZIP profile with fixed mimetype, canonical manifest/document records and SHA-256-addressed blobs. Bare encodings use explicit .nuif.json and .nuif.cbor names. Exact ZIP header fixtures, two independent local writers and bounded image/font segments now exist. Cross-platform and externally authored writer evidence remains required before package-profile acceptance.

Semantic document, resource and package hashes have different scopes. Stable asset identity is not content addressing. Unknown extension payloads remain explicit typed bytes/values and must not depend on accidental codec unknown- field behavior.

Collaboration

Canonical documents do not require CRDT tombstones, clocks or replica metadata. A collaboration profile maps NUIF operations to an append-only/change structure and can use Automerge, Yjs or another convergent transport. Checkpoints serialize back to canonical NUIF.

This keeps offline files simple and permits multiple collaboration engines.

The executable register profile uses causal multi-value registers. The separate existing-tree profile replays uniquely ordered moves, rejects cycles, models deletion as profile trash and orders siblings through stable RGA-style origins. Semantic move and deletion conflicts remain visible even when the profile can choose a deterministic checkpoint. Automerge is presently tested as an operation-set transport, not claimed as an implementation of the tree algorithm.

Governance

Early development occurs in refpath/nuif, but the architecture assumes eventual neutral stewardship. A plausible progression is:

1. OSS research/reference implementation under Refpath.
2. public RFC process + implementer registry.
3. independent community/working group once two independent implementations exist.
4. investigate W3C Community Group for UI/document semantics and/or Khronos-style governance if renderer/asset vendors become primary stakeholders.

Specification text, schemas and conformance tests need clear royalty-free contribution/IP terms before claiming standards-track stability.

Canonical source.

Prior art and competitive map

No surveyed system currently combines the whole NUIF thesis. Several solve important subsets.

Directly borrow

Stable standards concepts: SVG geometry, DTCG token values, Unicode/OpenType text foundations, CSS-compatible algorithms for matching profiles, glTF-style capability declarations, OpenUSD-style composition principles, MLIR-style dialect/lowering discipline.

Adapt

Retentive lenses → property/source correspondence; CRDTs → collaboration profile; WebRender/Vello/Skia → renderer boundary and conformance strategy; Tree-sitter → source-preserving adapter infrastructure.

Invent/prove

The proposed integration combines authored and resolved UI state, stable cross-tool semantic identity, opaque extension retention, fidelity accounting, bidirectional semantic patches and a native open editor whose internal state is the draft model itself.

Canonical source.

Implementation language and runtime choice

Decision: Rust reference core

Rust is the strongest default for the reference implementation because the project simultaneously requires untrusted binary parsing, graph/document transforms, geometry, text shaping, native/WASM embedding, GPU access, fuzzing and stable C-compatible boundaries.

Alternatives

• C++ has the deepest graphics ecosystem and mature Skia/Yoga integration, but expands memory-safety risk in parsers/plugins and makes a browser/WASM-safe reference core less attractive.
• Zig offers excellent systems control and C interoperability but has a smaller mature graphics/text/schema ecosystem and less API stability for a standards reference implementation.
• Go is strong for services/tooling but weaker for low-level rendering/WASM/native GUI integration and deterministic allocation-sensitive engines.
• TypeScript is ideal at web/editor adapter boundaries but unsuitable as the only renderer/codec/reference-core implementation.

Stack

• Rust: document model, operations, layout abstraction, codec, renderer scene, conformance, WASM bindings.
• Taffy: initial CSS-compatible evaluator behind NUIF types.
• Vello/wgpu: interactive renderer experiment behind a NUIF renderer trait.
• HarfBuzz-compatible shaping: text experiment with pinned font inputs.
• Masonry + AccessKit: reference editor shell (ADR 0006, accepted; toolchain 1.98.0, MSRV 1.96); Svelte 5 + TypeScript for the later browser demonstration over the WASM bindings.
• Tree-sitter/language-native parsers: source adapters where concrete syntax retention is required.

Adapters MAY be written in the ecosystem-native language; conformance is against behavior/protocol, not implementation language.

Canonical source.

Risk register and impossibility boundaries

Fundamental boundaries

1. Rendered output is underdetermined. Pixels/boxes cannot uniquely reveal whether layout came from flex, grid, constraints, absolute positioning or runtime code. Imported foreign content must mark inferred intent.
2. Arbitrary program behavior is not serializable as UI structure. NUIF does not promise to recover arbitrary JavaScript/Swift/Dart application logic.
3. Text is environment-sensitive. Font files, shaping versions, fallback and rasterization can differ. Exact conformance requires pinned inputs; portability must classify substitution separately.
4. Platform-native controls differ. Semantic equivalence may be possible while exact visuals/behavior are platform-specific.
5. Effects/shaders can exceed a portable core. Extensions may be preserved without being renderable.
6. Standard complexity can kill adoption. IFC/STEP demonstrate the cost of excessive semantic scope.
7. A single reference implementation can accidentally become the spec. Independent implementation is a standards gate.
8. Resource bytes carry legal and security constraints. Exact font/image preservation does not imply permission to redistribute or safe decoding.
9. Visual metrics are gameable. A flat screenshot can look exact while discarding editability, semantics, accessibility and responsive behavior.
10. Model confidence can be misleading. Raw probability is not calibrated correctness and cannot upgrade inferred evidence into source truth.
11. Capture can leak secrets. Browser/network/accessibility observations may expose credentials, personal data or proprietary content unless collection, export, retention and training are separately bounded.

Containment strategies

• explicit fidelity reports and inference confidence;
• authored + resolved snapshots instead of pretending either alone is canonical truth;
• opaque extension preservation;
• deterministic capability/evaluation contexts;
• small core + profiles;
• reference implementation backed by normative conformance fixtures;
• fuzzing/resource budgets for all untrusted inputs;
• early independent implementation and adapter experiments.
• stable asset IDs separated from resource digests, locators and provenance;
• verify resource size/digest before decoding and never fetch implicitly;
• typed operation output for models, atomic validation and finite correction loops;
• structural/text/resource/edit-task metrics alongside visual diagnostics;
• calibrated decision-level confidence, alternatives and abstention;
• private captures default to local processing, no retention and no training.

Current implementation risks

• The macOS graphics fork is a maintenance boundary. The editor pins refpath/xilem commit 1b96eb8; its parent eabfe0a moves the active renderer from wgpu 28 and metal-rs to wgpu 29 and the objc2 Metal bindings. The fork changes public API call sites and does not patch the Objective-C blocks ABI. Each fork update requires the editor tests, reverse dependency trace, and macOS Metal window smoke test recorded in nuif:research:macos-metal-block-future-incompatibility. A separate refpath/metal-rs move-to-block2 branch exists only for review; NUIF does not depend on the deprecated binding or that experimental patch.
• Release signing is credential-bound. The editor packaging gate builds, archives and smoke-tests an unsigned host package. Platform signing and notarisation require release credentials and remain separate from source conformance.
• Portable resources are only narrowly implemented. The deterministic package, RGBA8 PNG and static single-face TrueType subsets have executable gates, while CPU profile 0 remains unchanged. RFC 0010 cannot be accepted until broad media/font matrices, the configured Linux/Windows/macOS jobs produce passing hosted evidence, external reproduction, calibrated aggregate budgets and interoperability review pass.
• Capture and reconstruction accuracy remains unestablished. RFC 0011 and specification 14 now have bounded fixed-input contracts, a local pinned browser fixture and a typed synthetic evaluation report. They establish interfaces, refusal rules and metric consistency, not portable browser-capture or screenshot-reconstruction accuracy. No current release makes those accuracy claims.

Thesis falsifiers

The project should rethink its architecture if ordinary source round trips require broad regeneration, if unknown extension preservation cannot survive routine edits, if the layout vocabulary becomes a vendor-property dump, or if a second implementation cannot reproduce v0 behavior from specification + fixtures alone. The resource/reconstruction path should additionally narrow if package bytes cannot reproduce across writers, correction loops improve pixels by deleting semantics, confidence cannot support useful risk/coverage, or tuned models do not beat the untuned tool-assisted baseline.

Canonical source.

Governance and standardization strategy

NUIF starts under Refpath because research and implementation need a concrete home, but the target is neutral stewardship.

Repository governance now

• Public RFCs for semantic changes.
• ADRs for reference-implementation choices.
• Research evidence is distinct from normative requirements.
• Extension registry changes require examples and conformance fixtures.
• No vendor adapter can redefine core semantics.

Standardization path

A W3C Community Group is a plausible early venue for document/component semantics and coordination with Open UI/DTCG, but NUIF should not enter formal standards work before an executable v0 and at least one external implementer exist. Khronos/ASWF-style governance offers useful precedent for graphics/rendering and extension registries. A neutral foundation can become appropriate once multiple vendors/projects depend on the format.

IP/licensing goals

• reference code: permissive dual MIT/Apache-2.0;
• specification/schema/conformance text: permissive terms compatible with standards adoption;
• contributions: explicit patent/IP policy before standards-track claims;
• trademarks/conformance branding: separate from implementation copyright.

The project must not call itself an industry standard merely because the repository is public. Conformance, multiple implementations and neutral governance are prerequisites.

Canonical source.

Naming and project identity

NUIF is the current working name and repository slug, not yet a cleared standards trademark.

A public reconnaissance found prior acronym use in an old Nexus User Input Framework and in a 2024 computer-vision paper, plus unrelated uses. None currently appears to occupy the same open UI-authoring interchange category, but collision risk is non-zero.

The architecture therefore separates human branding from protocol identity. Stable schema namespaces, extension IDs and version identifiers must not depend on a product trademark remaining unchanged.

Before v0.1 branding is promoted outside the research project:

1. perform repository/package/domain/trademark clearance in key jurisdictions;
2. decide whether NUIF is an acronym or simply a proper project name;
3. reserve crate/package/extension namespaces;
4. define conformance-mark governance separately from the open specification;
5. make any rename before third-party persisted documents become common.

Canonical source.

Research coverage and continuous completeness

A research repository cannot truthfully claim to contain every paper that will ever be relevant. NUIF instead defines operational completeness: every planned architectural front must have an explicit status, evidence links, unresolved questions and an experiment/decision path.

research/coverage.yaml is the machine-readable coverage contract. It maps the founding research plan to research IDs, specification modules, RFCs/ADRs, code seams and experiments. The project can therefore identify gaps structurally rather than relying on prose search to infer that a topic was forgotten.

Current state

All founding fronts are represented. The resource, browser-capture, reconstruction-evaluation, adaptation/distillation and AI artifact-governance fronts are now explicit rather than hidden inside “serialization” or “inference.” Decisions that can safely be made from mature prior art are marked covered. Questions whose answer would be premature without an implementation are marked experiment-required. Areas whose evidence base will continuously evolve—prior art, adapters, reconstruction and data/model governance—remain ongoing by design.

This distinction is important: marking an open research problem as finished would be less rigorous than preserving it as a first-class graph node.

Additional boundaries from the final sweep

• WAI-ARIA and accessibility API mappings support a semantic-role/state layer distinct from platform-specific accessibility trees. The bounded nuif-web-accessibility-0 lowering now proves computed role/name/state agreement for one eleven-node fixture across pinned Chromium, Firefox and WebKit while retaining native-platform and behavior non-claims.
• KHR_interactivity provides contemporary precedent for portable, capability-aware behavior graphs rather than arbitrary scripts embedded in visual nodes. The smaller nuif-behavior-state-machine-0 sidecar now has exact Rust/Node traces for ordered guards, state, effects and explicit required/optional capability handling without claiming a final semantic schema. Its first wire experiment is one inert canonical-CBOR, content-addressed package resource: a Rust gate validates document binding and hostile cases while an independent Python ZIP reader checks exact container bytes. The attachment remains outside the canonical Document and never grants execution authority. A separate one-way web lowering maps the bounded effects through native activation, hidden and an ARIA status region; five events agree across pinned Chromium, Firefox and WebKit under one exact CSP-hash-authorized runtime without extending that evidence to native UI or screen-reader speech.
• ReverseORC and related layout-inference work show that multiple viewport observations materially improve recovery of responsive intent.
• Screenshot-to-code research continues to show that visual reconstruction is not equivalent to recovering authored layout or behavior.
• Merkle/content addressing is appropriate for immutable assets and snapshots but not for editable semantic identity.
• EPUB OCF and OCI descriptors support a narrow manifest-driven package with size/digest verification; NUIF now has an in-repository independent-writer fixture. A three-OS CI matrix now exercises the package, image and font gates, while successful hosted evidence and external reproduction remain open.
• OpenType and Fontations evidence now supports one executable static TrueType package baseline with a pinned HarfBuzz metadata oracle. The retired ttf-parser decision remains documented; broad font formats, portability outcomes and shaping/raster integration remain experiment-required. Warmed parser and packaged-validation allocation ceilings cover every accepted fixture.
• Browser source capture and screenshot reconstruction are different evidence lanes and cannot share a blanket lossless claim.
• Current screenshot-to-code work supports OCR/region/hierarchical and render- correction experiments, not a claim that authored UI recovery is solved.
• LoRA, quantized adaptation and distillation are conditional experiment techniques; evaluation, rights-cleared traces and artifact governance precede training.

The continuous-research process should periodically re-run topic searches, append or supersede research records, and update research/coverage.yaml only when new evidence or experiments change the status of a front.

Canonical source.

Cross-industry patterns: evidence, adoption and rejection

Document status: draft. Canonical source.

This document synthesizes 52 research records added on 2026-08-29 from visual-effects interchange, game-engine asset systems, programming-language research on bidirectional transformation and layout verification, distributed-systems testing, and 2D-rendering conformance practice. Each pattern below is classified as borrowed (adopted as is), adapted (adopted with a stated change) or rejected (ruled out with the reason). Record identifiers (nuif:research:*) carry the locators; this document does not repeat them.

Method

The 52 records synthesized here were reviewed from primary sources (specifications, source code at a named commit and papers with DOI). reviewed does not mean every material claim has completed locator-level verification; research/AUDIT.md defines the stricter verified state. Claims resting on one record inherit its evidence status as well as its confidence. Source conflicts remain explicit until an RFC or experiment resolves them.

Patterns

Document model and composition

Identity and ordering

Unknown data preservation and schema evolution

Operations, undo and merge

Canonical encoding

Layout

Rendering determinism

Text

Testing methodology

Editor automation

Ruled out

The following were examined and excluded from the architecture; the reason is recorded so the question is not reopened without new evidence.

• A self-describing binary struct layout (Blender DNA): solves version drift for one implementation but does not preserve data it cannot re-save and does not compose with a schema-versioned interchange model.
• Memento undo as the canonical history: does not commute, cannot be merged, and bloats logs; inverse operations are required by spec/06.
• Integer child indices in Move and Insert as the only order representation: non-commutative under concurrency; a list identifier is required for the collaboration profile and harmless for the canonical form.
• GPU rendering as a normative oracle: implementation-defined by the WebGPU and WGSL specifications.
• Perceptual UI screenshot tests as the primary editor test: platform-dependent text rendering makes them a shell-wiring check only.
• Heuristic tree matching for NUIF-native merges: unnecessary with stable identity and a source of spurious moves.
• Whole-project regeneration as the synchronization model: contradicted by the lens and delta-lens laws that NUIF’s patch model must satisfy (lenses-foster-boomerang, bidirectional-evaluation-direct-manipulation).

Consequences for the specification

The records imply the following changes. Items 1–3 were decided by follow-up research on 2026-08-29 and are recorded as accepted RFCs; items 4–6 remain proposals.

1. Sibling order is a canonical array without keys; Insert and Move use anchors (Start, After(id)); the collaboration profile maps anchors onto a Fugue-family list CRDT (RFC 0006).
2. nuif-cbor-0 follows deterministic preferred serialization while preserving integer/real data-model identity; real zero is positive floating zero, text and CBOR key orders are distinct, strict decoders reject non-canonical input, text hashes through CBOR and strings remain verbatim (RFCs 0005 and 0008).
3. Entities of unknown kind load as Unknown with typed core fields and an opaque payload; ignorant implementations preserve bytes, knowing ones may re-encode; validation severities follow the glTF pattern (RFC 0007).
4. Every serialized record kind carries a schema version; migrations are registered pure functions; newer-than-known versions load as Unknown for entities (RFC 0007) and are diagnosed for other records.
5. Validation, import and export reports follow one schema with stable codes, severities and pointers.
6. Layout conformance declares tolerance tiers per case and classifies every divergence from a browser reference as schema loss, evaluator defect or implementation-defined behavior.

Open questions raised by this synthesis

Recorded in research/questions.yaml: cbor-float-zero (decided, RFC 0005), sibling-order-identifier (decided, RFC 0006), unknown-kind-preservation (decided, RFC 0007), editor-toolchain-msrv (ADR 0006), layout-assertion-vocabulary, render-tolerance-tiers.

Resources, capture and model-neutral reconstruction

Document status: draft. Canonical source.

NUIF’s next research front is not “add an AI converter.” It is a coordinated resource, capture and reconstruction architecture with explicit truth boundaries. Images and fonts must survive as verified resources. Source-backed browser imports must retain authored/resolved evidence. Screenshot-only imports must remain honest probabilistic hypotheses. Every path converges through one core operation, validation, rendering and fidelity contract.

Decision summary

The recommended direction is:

1. define stable assets separately from immutable byte resources;
2. make .nuif a deterministic portable package after cross-writer proof;
3. grow the executable narrow PNG and static TrueType resource baselines only through named profiles and measured hostile-input budgets;
4. add a pinned browser-capture adapter separate from static source sync;
5. build screenshot reconstruction as a replaceable observation/proposal loop;
6. freeze a structural and visual evaluation suite before training;
7. consider adaptation or distillation only after the untuned loop exposes a repeatable learnable error distribution.

RFC 0010 and RFC 0011 remain proposed contracts. Their bounded package, narrow PNG/static-font and capture/reconstruction experiments are implementation evidence only for the named subsets; they are not published conformance or standards claims.

One core, two import lanes

Source-backed lane
HTML/CSS + browser execution + resource responses
      -> retained source + resolved observations
      -> deterministic adapter/lowering + explicit inference where needed
                              |
                              v
                    typed NUIF operations
                              |
                              v
                     core validation/apply
                              |
                              v
                      resource-aware NUIF
                              ^
                              |
Screenshot-only lane          |
pixels + context              |
      -> OCR/CV/grounding observations
      -> hierarchy/layout/resource hypotheses
      -> typed operations -> render/diff/correct

The lanes differ in evidence, not in their mutation authority. Both use the same typed operations. Neither provider can write core structs directly. A browser observation may support an exact resolved value under one pinned context, but it does not automatically reveal authored intent. A screenshot cannot establish source equivalence regardless of visual score.

Portable resource model

Four identities must remain distinct:

An asset points to a content descriptor containing media type, SHA-256 and byte length. A package path or external URL only locates candidate bytes; size and digest are checked before decoding. External resolution is opt-in. Opening a document never triggers network access.

Resource roles clarify hash and retention behavior:

• source: original encoded bytes;
• authoring: exact bytes needed to evaluate/edit semantics;
• derived: crop, trace, selected frame, conversion or generated result with input digests and transformation identity;
• cache: decoded pixels, GPU textures or acceleration state that can be deleted without changing the semantic document.

This avoids a common failure: storing only a decoded bitmap and calling the source image preserved, or hashing an editable asset by its current bytes and therefore breaking every reference after replacement.

Candidate .nuif package

The proposed first package is a deliberately small deterministic ZIP profile:

mimetype
manifest.cbor
document.cbor
blobs/sha256/<digest>

mimetype is first and stored. Manifest and document are deterministic CBOR. Every embedded blob is addressed by exact SHA-256 bytes. The first profile uses stored members only, fixed metadata and sorted ASCII paths to make independent writer byte equality attainable and to avoid compression-version variability.

There are three hashes:

• semantic document hash over canonical document.cbor;
• resource digest over each exact blob;
• package hash over the exact ZIP artifact.

Cache or report changes may change the package hash while leaving the semantic document hash untouched. Bare canonical forms remain .nuif.json and .nuif.cbor. Historical alpha .nuif raw files need read-only detection during migration; new .nuif output becomes the package only after RFC acceptance.

The package reader rejects duplicate or unsafe paths, symlinks, directories, encryption, split archives, unsupported compression, inconsistent headers, undeclared/missing blobs and digest mismatch. It does not extract to a filesystem. Exact byte fixtures, member/resource limits and two independent writers are acceptance gates.

Package-to-session handoff uses shared immutable buffers. The release gate passes an 8 MiB resource through package, handle map and session with the same allocation pointer while keeping handoff allocator traffic and retained bookkeeping below 1 MiB. This prevents a host from paying one full resource copy merely to enter the core.

Images

The original encoded image is authoritative. A semantic image asset records its resource digest and intrinsic interpretation; each image paint records fit, crop, transform, sampling, opacity and color conversion. Derived decoded pixels and GPU textures are caches.

PNG is the correct first format because its current W3C specification covers lossless encoded pixels, alpha and explicit colour metadata. The executable nuif-png-rgba8-0 baseline chooses an intentionally smaller contract: non-interlaced RGBA8, no ancillary metadata or one valid sRGB chunk, encoded samples interpreted as sRGB, straight decoded alpha, identity encoded orientation, declared fit/crop/sampling/opacity and bounded integer CPU composition. png 0.18.1 and zune-png 0.5.2 must emit identical RGBA bytes for the accepted fixtures; encoded resources remain digest-identical through package edits.

This avoids pretending that decoder agreement on simple images settles PNG Third Edition. The compatible nuif-png-basic-rgba8-1 profile now admits the lossless-to-RGBA8 subset: 1/2/4/8-bit greyscale and indexed images, RGB8, greyscale-alpha8, RGBA8 and valid palette/colour-key transparency. It preserves encoded bytes and requires exact normalized RGBA agreement between both decoders. It is separately named so profile zero never changes meaning.

Image-paint affine semantics are orthogonal to decoder choice. The executable matrix [a c tx; b d ty; 0 0 1] maps crop-local source coordinates forward into the fitted rectangle. The CPU reference inverse-maps destination pixel centers, clips to the entity, and rejects singular or numerically unbounded matrices. Flip, rotation and translation fixtures make composition order observable; live host trials are still required for vendor interoperability.

Decoded pixels are interned once per digest/profile in the renderer-independent scene and commands carry compact deterministic handles. A 64 MiB total is preflighted before each new inflation. The release gate retains one 1 MiB surface for 1,024 image instances under 8 MiB allocated and 4 MiB retained, and rejects a 64 MiB plus 16 byte declared total before the second decode.

Any broader profile still has to pin:

• accepted chunks and metadata conflicts;
• color-space precedence and output space;
• Exif orientation;
• conversion and premultiplication points for every accepted colour signal;
• sampling and compositing;
• encoded, pixel, decoded-byte, chunk and metadata limits;
• independent decoder and malformed-input fixtures.

16-bit/interlaced PNG, CICP/ICC/gamma/chromaticity, Exif, animation, perspective/tiling and host-specific affine equivalence are not claimed. A Linux/Windows/macOS CI matrix runs the profile, but the cross-platform claim remains withheld until its hosted artifacts pass. JPEG, WebP, AVIF, video and SVG follow as separate profiles. Freezing a frame or tracing a screenshot crop is a derived approximation, not recovery of the original asset. Generative upscaling/inpainting requires an explicit user policy and cannot silently become canonical source evidence.

Fonts

Exact typography depends on exact font bytes, face/collection index, variation axes, features, coverage, shaping inputs and renderer parameters. Packaging also depends on redistribution policy.

The proposed policy states are portable, private_authoring, linked, substituted and unavailable. OpenType fsType is preserved as machine- readable evidence, including restricted/preview/editable/no-subsetting/bitmap flags, but is not treated as a complete legal license decision.

The executable nuif-opentype-static-single-0 baseline accepts only one canonically packed, checksummed TrueType-outline sfnt face at index zero. Skrifa 0.46.2 supplies package-facing metadata after NUIF validates the directory, ranges, packing and checksums and directly checks required sfnt and OS/2 fields. A committed hb-info 14.4.0 capture independently checks Ahem metrics, family, tables and Unicode coverage. Exact bytes, family names, coverage, fsType, license expression and explicit embedding review must agree. Package encode/decode and caller-resolved linked bytes run the same validation. Four static TrueType fixtures are accepted, while six package trials distinguish portable, private-authoring, linked, substituted and unavailable outcomes. Each accepted inspection and packaged-font validation is also measured after warmup against a 4 MiB allocator-traffic and 2 MiB retained reference ceiling; these are implementation regressions, not format semantics. Six additional trials retain requested identity separately from a stable font asset, render with an available declared replacement as approximated, and emit no text command with item-level unsupported fidelity when replacement bytes or the font are unavailable.

This is intentionally not general OpenType support. TTC, CFF/CFF2, variable, color, bitmap, SVG and WOFF/WOFF2 sources, historic ambiguous permission combinations, subsetting, cluster-level fallback, arbitrary packaged-font shaping and cross-platform raster behavior remain separate fixtures and profiles. The configured three-OS parser/package matrix does not establish cross-platform raster behavior. Parser acceptance and fsType do not grant redistribution rights.

Browser capture can identify platform fonts used for a node and capture downloaded web-font response bodies. It generally cannot retrieve arbitrary local font bytes. A family/PostScript name is therefore never exact resource identity. Missing bytes produce a link, substitution or unavailable fidelity record instead of a false portable-font claim.

Source-backed browser capture

Static Tree-sitter source synchronization and live browser capture solve different problems. The former preserves source spans for a bounded authored subset. The latter runs a pinned browser to observe actual cascade, layout, fonts, resource responses, accessibility and pixels. They should correlate through provenance, not become one oversized adapter.

The first browser-capture profile records browser/protocol build, OS, viewport, DPR, page scale, locale, timezone, color/reduced-motion preferences, font environment, scroll/pseudo state, navigation identity, readiness/network policy and animation freeze. It collects:

• original HTML/CSS and stylesheet text where accessible;
• DOM snapshots including available frame/template/shadow content;
• boxes, inline text boxes, paint order and a bounded style set;
• downloaded image/font/style response bodies and hashes;
• platform-font usage and font readiness;
• accessibility tree;
• reference screenshots with exact parameters.

Canvas, WebGL, video and worklets are bounded observation surfaces; a frame can be preserved without pretending its generating program was reconstructed. Cookies, authorization headers, credentials, storage and secret form values are not exported. Scripts remain inert.

Multiple viewports and states are more valuable than one oversized capture: they constrain layout hypotheses and permit held-out responsive evaluation.

The automated nuif-cdp-live-0 segment now implements that boundary for one loopback fixture and exact Chrome for Testing 152.0.7977.64. It starts fresh temporary profiles, retains a structured runtime context, waits for the exact navigation loader and declared freeze/readiness point, captures bounded DOM/layout/background/font/accessibility/resource/PNG evidence, and replaces opaque browser node IDs with deterministic preorder identities. Four runs at 360, 768, held-out 900 and repeated 360 px retain exactly the expected five response bodies and repeat the narrow capture bytes. Five exercised query/cookie/storage/authorization/header canaries are absent from serializable capture, observations, proposals and package bytes. The two fitted viewports beat the one-viewport freeform baseline on the held-out fixture.

The separate bounded nuif-layout-inference-0 artifact ranks row stack, column stack, Grid, linear constraint and fixed freeform candidates using only the 360/768 px observations. It then evaluates the untouched 900 px holdout, where the selected constraint records 0.0626 normalized error versus 0.2918 for freeform. All alternatives and exact geometry observation identities are retained; confidence is raw and uncalibrated, and the result remains inferred. The trial tests a mechanism on one fixture, not general accuracy or recovery of original authored intent.

This is a falsifiable local baseline, not the entire profile described above. Cross-browser/OS reproduction, opaque frames and response bodies, full matched-style/source correlation, canvas/video frame capture, authenticated sites and licensed real-page evaluation remain open. WebDriver BiDi is the standards-track transport to revisit as its implemented evidence surface grows; Playwright is the higher-level candidate when NUIF owns a real multi-engine matrix and can make one tool the browser-version authority.

Screenshot reconstruction

A screenshot supplies visible samples but not the unique scene graph or layout program. The recommended pipeline is:

screenshots + contexts
  -> OCR and baselines
  -> deterministic regions, colors, edges, repetitions and asset candidates
  -> optional replaceable UI grounding
  -> typed observation graph with confidence and evidence regions
  -> replaceable reasoner proposes hierarchy/layout and NUIF operations
  -> core validates and applies atomically
  -> deterministic layout/render
  -> text/structure/geometry/resource/visual differences
  -> bounded corrective operations

The model emits typed operations, not an unconstrained full document or code to execute. Invalid and stale transactions fail without partial state. High- resolution full views, overlapping tiles and semantic crops share explicit coordinate transforms; duplicate or conflicting observations remain visible.

The result contains a valid document or no-result, accepted operation log, observations, derived resources, item fidelity, alternatives/abstentions, evaluation report and exact pipeline artifact identities.

Evaluation before training

The benchmark has separate synthetic-exact, licensed real screenshot and source-backed suites. Synthetic NUIF rendering provides exact entities, properties, operations and resources. Real images need human-reviewed visible targets and must preserve ambiguity. Source-backed cases evaluate retained bytes and observations unavailable to the screenshot-only route.

Required metrics include:

• valid operation/document rate;
• OCR region recall, character/word error and baselines;
• element precision/recall and hierarchy error;
• property/geometry accuracy;
• held-out viewport behavior;
• exact resource digest only when bytes exist;
• provenance/fidelity honesty;
• accessibility evidence where justified;
• raw pixels, FLIP, SSIM and pinned LPIPS diagnostics;
• calibrated confidence, abstention and risk/coverage;
• latency, peak RAM/VRAM, iterations and cost.

No pixel score is sufficient. A page-sized screenshot can be visually perfect and semantically useless. Structural/text/resource/edit-task metrics prevent that reward shortcut. Dataset splits group by origin, template, component, font, resource and generator; near duplicates cannot cross splits.

The executable nuif-reconstruction-corpus-manifest-0 turns that rule into a bounded audit. It pins the data snapshot, dataset card, evaluator and every input/target by digest; records public/restricted/withheld disclosure and evaluation/calibration/adaptation/redistribution permission independently; and rejects exact artifact or declared family reuse across adaptation, calibration, validation and test. Private/authenticated records also require explicit authorization and a withdrawal-policy artifact. This is declaration integrity, not automated legal review or duplicate discovery; real records and their group assignments still need independent human/tool review.

The ablation ladder is deterministic OCR/CV, one-shot reasoner, observation- assisted reasoner, hierarchical crops, multi-viewport ranking, correction loop, then any tuned or distilled student. Every addition uses the same frozen holdout and budget.

Adaptation and distillation

Training is justified only after the untuned loop and error taxonomy are reproducible, rights-cleared traces exist, and the remaining errors appear learnable. Training examples contain input hashes, observation versions, proposals, diagnostics, accepted operations, intermediate renders/differences and final package/fidelity reports. Positive sequence targets are validated accepted transitions, not raw model transcripts.

Compare prompt/schema/tool improvements and retrieval before fine-tuning. If adaptation remains justified, compare ordinary supervised tuning, low-rank adaptation and quantized low-rank adaptation under equal data and evaluation. Quantized adaptation is a memory technique, not an accuracy claim.

Sequence-level distillation may train a smaller student from the best evaluated teacher pipeline. The teacher is a measured system of tools plus a model, not a provider name. Distillation transfers errors too, so render validation and held-out evaluation remain mandatory.

Models, processors, adapters and datasets are separately versioned optional artifacts with digests, model cards, dataset datasheets, license lineage and training manifests. They never redefine nuif-core or travel as ordinary document resources.

The executable provider boundary uses a deliberately small canonical wrapper, not a new AI bill-of-materials vocabulary. It binds NUIF capabilities, execution modes and observation/proposal profiles to exact implementation, model, processor, adapter, quantization, prompt and tool artifacts. Observation bundles carry the complete manifest registry, so a digest cannot dangle and a proposal cannot substitute an unpublished provider before mutation. Released or learned providers point to content-addressed SPDX 3.0.1 or CycloneDX 1.7 inventory; learned providers also point to a model card. This complements runtime packaging such as MLflow or ONNX external data without making either a required NUIF dependency.

Private/authenticated captures default to local processing, no retention and no training. Remote transfer, telemetry, retention and training are independent consent/policy decisions.

Maturity boundary

The current 0.1.0-alpha.3 label belongs to the developer editor application. It provides no evidence that the broad image/font resource, portable browser capture or screenshot reconstruction accuracy profiles are complete. A deterministic package, narrow PNG/static-font segments, fixed provider-input contracts and one pinned local live-browser segment are implemented, but their deliberately narrow evidence does not promote the broader profiles.

Promotion requires the package/resource cross-writer fixtures, pinned capture reproduction, baseline/closed-loop/calibration harness, leak-resistant licensed evaluation data, independent result reproduction and at least one real edit workflow that benefits from the inferred semantics. Until then the work is research and proposed specification text, not a standard or production reconstruction promise.

Primary research records

• nuif:research:resource-packaging-and-source-capture-synthesis
• nuif:research:model-agnostic-screenshot-reconstruction-and-training
• nuif:research:provider-artifact-manifests-and-ai-boms
• nuif:research:epub-ocf-package-container
• nuif:research:oci-resource-descriptors
• nuif:research:opentype-font-embedding-and-portability
• nuif:research:ttf-parser
• nuif:research:fontations
• nuif:research:chromium-source-backed-ui-capture
• nuif:research:live-chromium-cdp-capture
• nuif:research:design2code-real-world-benchmark
• nuif:research:pix2struct-screenshot-parsing-pretraining
• nuif:research:screenai-ui-annotation
• nuif:research:confidence-calibration-and-selective-prediction
• nuif:research:lora-low-rank-adaptation
• nuif:research:qlora-quantized-adaptation
• nuif:research:sequence-level-knowledge-distillation

NUIF specification

Document status: pre-draft. No module or conformance profile is published as an. Canonical source.

accredited standard.

This directory contains the candidate normative text. Research documents can motivate semantics but cannot silently define them. The current modules remain draft inputs until their status, licensing terms and corresponding conformance requirements are published through the governance process.

Planned modules

• Core document and identity model
• Components, instances, parameters, variants, and slots
• Layout and responsive evaluation
• Geometry, paint, color, typography, and assets
• Tokens and themes
• Interaction/state and data binding
• Operations, transactions, diff, patch, and reconciliation
• Extensions/dialects and capability negotiation
• Serialization and package format
• Observation, capture, reconstruction, confidence, and inference provenance
• Conformance, diagnostics, fidelity, and security

A specification statement becomes normative only when its module explicitly declares normative status and the conformance suite contains corresponding executable tests.

Conformance and fidelity

Document status: draft. Canonical source.

A conforming implementation MUST NOT silently discard semantically relevant information. Import, lowering, migration, and export operations MUST be able to emit structured diagnostics.

Initial fidelity classes are:

• lossless
• representable
• approximated
• preserved_unrenderable
• unsupported

Capability profiles will identify which optional modules and extensions an implementation can evaluate, render, mutate, and preserve.

Unknown extensions MUST be preserved byte-for-byte or canonical-value-for-canonical-value when the package/encoding permits preservation and when doing so does not violate security policy.

Logical model

Document status: draft. Canonical source.

The working NUIF model is a layered hybrid rather than a universal AST.

Identity

Every durable authored entity has a stable EntityId. Identity is independent from display names, containment position, serialization offsets, and vendor IDs. External correspondences are recorded separately as provenance.

Containment

Documents contain ordered authored entities. Containment expresses lifetime/ownership and author-facing hierarchy only.

Coordinated relations

Relationships that are not ownership belong in typed relation sets/graphs: component-instance links, token references, constraints, interactions, state transitions, dependencies, provenance, and extension-defined relations.

Authored and resolved data

Authored data expresses intent. Resolved data is derived for a named evaluation context such as viewport, scale, font environment, capability profile, and theme. Resolved data is cacheable/reproducible output and MUST NOT overwrite authored intent.

Extensions

The core admits namespaced extension values. An implementation may understand, preserve without understanding, approximate, or reject an extension according to declared capability and security rules.

02 — Identity and properties

Document status: draft. Canonical source.

Entity identity

Every authored entity MUST have a stable 128-bit-or-greater identifier. Identity MUST NOT depend on name, path, child index, geometry or serialized byte offset. Implementations MAY use UUIDv7/UUIDv4-compatible identifiers; the normative requirement is uniqueness and stability, not one generation algorithm.

Immutable assets MAY additionally use cryptographic content IDs.

Property model

A property is addressed by (entity_id, namespace, key). Core properties use the nuif namespace. Published extensions use registered namespaces and vendor extensions use registered vendor identifiers.

Properties distinguish:

• authored value;
• token/expression binding when present;
• resolved value for an evaluation context;
• provenance/correspondence metadata.

Resolved values MUST NOT overwrite authored values.

03 — Components and composition

Document status: draft. Canonical source.

A Component is a reusable authored definition with typed parameters and named slots. An Instance references a component and carries parameter values and non-destructive overrides.

Core parameter classes: boolean, number, string/text, enum, token reference, asset reference and content/slot value.

Variants are named parameter configurations, not duplicate component definitions.

Composition supports references to external NUIF libraries and ordered override layers. Themes and brands SHOULD be expressed as token/layer opinions rather than destructive copies.

DTCG-compatible design tokens are the default token interchange representation. NUIF bindings add stable token identity and resolved context values.

04 — Layout

Document status: draft. Canonical source.

NUIF defines authored layout separately from resolved layout.

Core families

freeform, stack, flex, grid, constraint and extension-defined custom.

Shared sizing

Axes support fixed, auto/intrinsic, min-content, max-content, fit-content, percentage and fill/available sizing plus min/max clamps and aspect ratio.

For the CSS-compatible stack/flex subset, stretch applies only when the item’s cross-axis size is auto; an explicit fixed, intrinsic, percentage or fit-content cross size wins. fill is an explicit request for the available cross size regardless of the container’s alignment. This distinction is covered by the Gate C foreign-reference regression.

Responsive rules

Conditional authored values use predicates over declared evaluation features: viewport/container dimensions, orientation, input capability, theme/media preference and named application conditions. Predicates MUST be deterministic for a supplied evaluation context.

Resolved layout

An evaluator emits boxes/transforms plus diagnostics and the context fingerprint. Resolved geometry may be cached/serialized but is derived unless the authored family is freeform.

Portability

Lowering to a target layout model MUST return fidelity records for every rule that is approximated, preserved-unrenderable or unsupported.

Bounded explicit Grid

Profile 0 defines a deliberately finite Grid subset. It is a portable authored layout primitive, not an alias for the complete CSS Grid algorithm.

A grid container MUST declare one or more columns and one or more rows in its layout.grid value. Each track is either:

• fixed(n), where n is a positive finite pixel length; or
• fraction(n), where n is a positive finite flexible weight.

Profile 0 permits at most 256 tracks on either axis and 4,096 grid tracks in a document. It has no intrinsic, percentage, auto, repeated, named, subgrid, masonry or implicit tracks. Importers MUST report those foreign features as a loss, approximation or preserved extension rather than silently lowering them to this subset.

The one container gap is used for both axes. For one axis, let inner be the non-negative content-box length after padding, gaps be gap * (track_count - 1), fixed be the sum of fixed tracks, and weight be the sum of fractional weights. Track sizes are:

remaining = max(0, inner - gaps - fixed)
fr        = remaining / max(1, weight)
fixed(n)  = n
fraction(n) = n * fr

The max(1, weight) rule intentionally follows CSS Grid’s fractional sizing rule for a total flex factor below one. Fixed tracks can overflow the content box. Fractional tracks never receive negative space, and a fractional weight sum below one can leave unused space at the end of the axis.

Grid-item column and row are zero-based explicit track indices. An item MUST provide both or neither. column_span and row_span default to one and MUST be positive. Explicitly positioned items reserve their complete rectangular areas before any auto placement, independent of child order. Overlap and out-of-bounds areas are invalid.

Items with neither index are placed in child order. auto_flow: row scans rows then columns; auto_flow: column scans columns then rows. Scanning begins at the first cell and a cursor advances past the last placed item’s span. Each item occupies the first unoccupied rectangle at or after that cursor that fits its spans. The cursor does not move backwards to fill earlier holes; this is the sparse CSS grid-auto-flow behaviour, not dense. The explicit grid is exhausted when no such rectangle exists; an evaluator MUST NOT create implicit tracks.

An item’s grid area includes the gaps crossed by its spans. fill consumes the area on that axis. auto consumes the area when container alignment is stretch, otherwise it resolves to intrinsic size. Other size intents resolve against the grid-area length. start, center and end place the resulting box on both axes; stretch places it at the area’s start and only stretches auto or fill. Authored freeform position is ignored for an in-flow grid item. Descendants are evaluated within the resulting item box.

Using layout.grid on another layout family, using non-default grid placement without a direct Grid parent, or using the grid family without valid explicit tracks is invalid. This removes the former stack-flow fallback: a conforming implementation either implements these semantics or reports the Grid feature as unsupported.

Differential context

CSS-compatible layout claims are checked against exact pinned Taffy and browser versions. The machine report MUST retain the generator source revision, browser executable/version, seed, viewport, all compared boxes, per-fixture measured tolerance and a typed classification for every value outside that tolerance. A global unexplained tolerance is not conforming evidence.

05 — Geometry, paint and text

Document status: draft. Canonical source.

Geometry follows established 2D vector mathematics: affine transforms, rectangles/rounded rectangles, ellipses, lines and Bézier paths. Path semantics SHOULD align with SVG where possible.

Paint supports solid colors, gradients, images, strokes, opacity, clipping/masks and compositing/blend modes. Color values MUST declare a color space; conversions are evaluator responsibilities.

Asset and resource boundary

An asset is a semantic entity with stable AssetId. A resource is an immutable byte sequence identified by ResourceDigest. Package paths and external locators are resolution hints and MUST NOT be used as either semantic or byte identity.

Replacing the bytes bound to an asset MUST be expressed as a semantic operation that preserves AssetId and changes its ResourceDigest. Every resource descriptor declares media type and byte length. An implementation MUST verify the declared size and digest before media-specific decoding.

Resource roles are:

• source — exact bytes received from an origin;
• authoring — bytes required to evaluate or edit the semantic document;
• derived — bytes produced from named inputs by a declared transformation;
• cache — deletable acceleration data that cannot affect semantic hashes.

Derived resources MUST identify all source digests and the transformation artifact/profile. A crop or trace created from a screenshot is derived; it MUST NOT be presented as the original source asset.

Image assets

ImageAsset records AssetId, current encoded-resource digest, intrinsic pixel dimensions and decoder profile. ImagePaint refers to the asset and records fit, crop, affine transform, sampling, opacity and color-conversion policy. Decoded pixels and GPU textures are caches keyed by encoded digest plus decoder profile.

Renderer-independent scenes MUST store a unique decoded surface once per resource-digest/decoder-profile pair and reference it from image commands. The reference scene budget is 64 MiB of decoded RGBA surfaces and MUST be checked from bounded metadata before allocating the next decode.

The affine fields use [a c tx; b d ty; 0 0 1] and map the selected crop’s normalized source coordinates forward into normalized coordinates of the fitted paint rectangle. Fit is calculated first. Rasterizers inverse-map destination pixel centers, apply crop selection after that inverse, and clip to the entity rectangle. The origin is the fitted rectangle’s top-left; callers encode any center-origin adjustment in the translation. Executable matrices MUST be finite and invertible. The reference bound rejects components or inverse components above 1,000,000 in magnitude and determinant magnitudes below 1e-12 as unsupported fidelity.

The first executable image profile, nuif-png-rgba8-0, is PNG-only and deliberately narrow. It accepts non-interlaced RGBA8 with no ancillary chunk or one valid pre-image sRGB chunk, interprets the encoded samples as sRGB and keeps alpha straight through decoding. It rejects palette, grayscale, RGB-only, 16-bit, CICP, ICC, gamma/chromaticity, Exif, animation, arbitrary ancillary chunks and trailing bytes. Its exact chunk sequence, dimensions, pixel/byte budgets, fit/crop, bounded affine transform, nearest/fixed-bilinear sampling, opacity and encoded-sRGB integer composition contract is in crates/nuif-media/PROFILE.md. JPEG, WebP, AVIF, animation, video and SVG are unsupported by that profile rather than silently decoded through host defaults.

The separately named nuif-png-basic-rgba8-1 profile accepts the non-interlaced PNG colour/depth combinations that normalize to RGBA8 without sample-precision loss, including required palettes and valid tRNS transparency. It does not change profile zero and still rejects 16-bit, interlaced and colour-managed inputs. Its exact matrix is also in crates/nuif-media/PROFILE.md.

An animation or video adapter MAY create a derived still resource when it records source digest, selected frame/time, decoder profile and item-level loss. SVG is evaluated only through a declared safe adapter profile; otherwise its bytes remain inert and preserved.

Font assets and portability

Text stores Unicode scalar content, style runs, paragraph attributes, direction/language hints and a requested content-addressed font identity. A font SHA-256 reference MUST contain 64 lowercase hexadecimal digits. Font size and line height MUST be finite and positive. An optional font_asset binds the text item to a stable font asset; a family or PostScript name is never a substitute for that identity.

A font asset additionally records media type, face or collection index, names used for matching, variation axes, feature selections, coverage and portability policy. The policy is portable, private_authoring, linked, substituted or unavailable. OpenType embedding flags and explicit license metadata are policy evidence; the format does not claim to make a complete legal decision.

A portable package MUST NOT embed a font whose effective export policy forbids that embedding. Linked fonts retain expected digest and explicit resolver hint; resolution is opt-in and digest-checked. Substitution and unavailability MUST produce item-level fidelity. Family/PostScript names alone MUST NOT satisfy an exact-font profile.

For an exact binding, the asset resource SHA-256 MUST equal the requested text hash. For a substituted binding, the text retains the requested hash and the asset resource identifies the exact replacement bytes. For an unavailable binding, the asset MUST carry no resource. Layout and rendering MUST use an available declared replacement with approximated fidelity; if replacement bytes are absent, or the asset is unavailable, rendering MUST emit no text command and MUST report item-level unsupported fidelity. Resolution MUST NOT query a platform font database or perform I/O.

The first executable resource subset, nuif-opentype-static-single-0, accepts only one canonically packed, checksummed TrueType-outline sfnt face at index zero. It requires exact font/ttf bytes, matching family names and Unicode coverage, no variation axes, matching fsType evidence, a non-empty license expression and an explicit embedding review. It rejects TTC, CFF/CFF2, variable, color, bitmap, SVG and WOFF/WOFF2 sources. Exact limits and non-claims are versioned in crates/nuif-font/PROFILE.md. This narrow package resource profile does not establish shaping or raster equivalence.

A conformance profile that compares resolved text MUST declare the exact font bytes and hash, shaper and Unicode-data versions, direction, language, script-selection rule, feature set, cluster level, cluster coordinate unit, positioning unit and resource limits. Resolved runs contain source text plus ordered glyph identifiers, clusters, advances and offsets; they MUST NOT depend on system font discovery. Profile 0 uses Unicode-scalar indices for cluster coordinates and unscaled font units for advances and offsets.

Shaping and rasterization are distinct conformance stages. A shaping pass does not imply raster conformance. A raster profile MUST additionally declare outline extraction, hinting, stem darkening, anti-aliasing, subpixel quantization, color/blend space and compositing rules. Until those parameters and their foreign/cross-platform trials exist, an implementation MUST classify a glyph-ID bitmap proxy as approximated rather than exact text rendering.

Implementations MUST preserve source text even when resolved glyph information is present.

CPU render profile 0

Profile 0 is deliberately narrower than the complete model. Its supported visual operations are encoded-sRGB solid fills of rectangles and ellipses, plus the text subset below. Color channels are finite numbers in the inclusive range 0 through 1. The reference raster starts as opaque white RGBA8.

Logical geometry is multiplied by the target scale factor before rasterization. A rectangle covers every pixel in floor(x)..ceil(x + width) and floor(y)..ceil(y + height), clipped to the target; it does not compute fractional edge coverage. Float color channels become bytes with round(clamp(channel, 0, 1) × 255). For mask coverage coverage, effective source alpha is (source_alpha × coverage + 127) / 255 using integer division. Each encoded-sRGB destination color channel becomes (source_channel × alpha + destination_channel × (255 - alpha) + 127) / 255; output alpha remains 255.

An ellipse is the closed four-cubic path inscribed in its bounds using control coefficient 0.551915024494. It is rasterized with nonzero fill into an 8-bit grayscale mask by Zeno 0.3.3, crates.io checksum 6df3dc4292935e51816d896edcd52aa30bc297907c26167fec31e2b0c6a32524, then composited by the integer rule above. conformance/render/profile-zero-v1.json fixes rectangle and ellipse scene/PNG hashes on the recorded platform matrix.

Profile-0 text uses Ahem 1.50, HarfRust 0.13.3 with Unicode 17.0.0, unhinted Skrifa 0.46.2 outlines in signed 26.6 font units, and Zeno 0.3.3 grayscale masks. CRLF is one hard break; CR, LF, NEL, LINE SEPARATOR and PARAGRAPH SEPARATOR are individual hard breaks. Each hard line is shaped independently. Intrinsic width is the greatest shaped line advance; intrinsic height is the number of hard lines times line_height. The first baseline is 800 Ahem font units below the line top, subsequent baselines differ by line_height, LTR starts at the left edge, RTL starts at the right edge, and output is clipped to the text box. Profile 0 performs no automatic soft wrapping. Because wrapping is not an authored property in this profile, absence of soft wrapping is exact profile behavior rather than an approximation.

Path geometry, image assets, component-instance materialization and extension-defined paint/effects are not supported by CPU render profile 0. Lowering MUST emit unsupported or preserved_unrenderable fidelity with the originating entity and property pointer; it MUST NOT substitute bounds rectangles or silently omit the data. nuif-png-rgba8-0 is an orthogonal experimental image segment and does not change profile-0 results. Future profiles may compose accepted segments explicitly.

The asset and broad-font requirements above remain draft inputs for broader profiles. The narrow executable image and static-font resource segments do not implicitly enter CPU render profile 0.

06 — Operations, patches and merge

Document status: draft. Canonical source.

Operations are stable, serializable semantic mutations. Core operations include entity insertion/removal/move/rename; typed size, position, layout, fill and text edits; generic authored-value edits; token and extension edits; and transaction grouping. SetPosition, SetFill and SetText replace their complete typed property and therefore have exact inverse operations. An editor that applies several related controls together MUST place them in one transaction so validation and undo remain atomic.

Position (RFC 0006)

Sibling order in the canonical document is an ordered array of entity identifiers without keys, tombstones or replica metadata. Insert and Move specify position as an anchor, Start or After(entity), never as an integer index. An anchor MUST refer to a current child of the target parent; otherwise the operation fails with AnchorMissing. A move into the moved entity or its descendants fails with CycleRejected. Insertions at the same anchor within one patch apply in patch order.

Patches

A patch’s optional base_revision, when present, is the profile-qualified canonical content hash of the document to which it applies. An implementation MUST reject a mismatch before applying any transaction. Transactions and operations are ordered. Preconditions MAY guard expected prior values, including ParentIs and Follows.

Undo is represented as inverse semantic operations or transaction history; it is not part of canonical document state. A generated inverse patch declares the hash of the post-apply document as its base_revision. The invariant “undo, copy, redo leaves the document unchanged” is a conformance relation.

Merge

Three-way merge MUST prefer stable identity; structural matching is reserved for adapters without identity. Implementations MUST surface typed conflicts rather than selecting arbitrary winners: property, delete/edit, ordering (OrderAmbiguous, informational, ordered by declared branch precedence), move (MoveConflict), relationship, extension and semantic-lowering conflicts. Conflict objects are document state until resolved.

Merge rules per property kind (ordered list, identity set, scalar with tolerance) are declared by the schema so that structural merges are deterministic.

Unknown entities (RFC 0007)

Remove, Move, Rename, SetExtension, RemoveExtension and core-property operations apply to entities of unknown kind unchanged. SetUnknownPayload is valid only for implementations that declare the payload’s namespace.

07 — Extensions and dialects

Document status: draft. Canonical source.

NUIF uses a small core and namespaced extensions.

Documents declare extensions_used and extensions_required, and MAY declare a fallback_kind per namespace. A required extension means correct interpretation/rendering cannot be guaranteed without it.

Extension lifecycle namespaces use the lowercase identifier grammar from RFC 0005:

• nuif.* — ratified NUIF extension;
• ext.* — multi-implementation experimental extension;
• a collision-resistant vendor/project namespace such as a reversed DNS name — owner-specific extension.

Preservation (RFC 0002, RFC 0007)

Unknown extension payloads MUST be preserved at their attachment point unless an operation explicitly removes the owning entity/property. An implementation that does not declare a namespace preserves its payloads byte-for-byte; one that declares it MAY re-encode deterministically. Payloads are opaque byte strings with a declared encoding (Cbor or Octets); a malformed payload yields a diagnostic on its owner and does not invalidate the document.

An entity of unknown kind, or of a known kind with a newer schema version than supported, loads as Unknown with namespace, kind name, schema version and payload retained; its core fields stay typed and editable; layout uses the declared fallback_kind or Container; rendering reports preserved_unrenderable.

Validation

• namespace present but not in extensions_used: error;
• namespace in extensions_used and unsupported: information;
• namespace in extensions_required and unsupported: blocks faithful-rendering claims, never structural editing.

Promotion of an ext.* namespace to nuif.* requires a conformance fixture and a validator rule (adapted from the glTF extension status ladder).

Dialects may define higher-level authored constructs and lowering rules. A dialect cannot redefine core semantics.

08 — Serialization and package format

Document status: draft. Canonical source.

The NUIF logical model is encoding-independent.

Initial profiles:

• nuif-text-0 — deterministic human-readable canonical form for fixtures/review.
• nuif-cbor-0 — deterministic CBOR following draft-ietf-cbor-serialization §4.1 (preferred serialization) and §5.1 (bytewise-lexicographic map key order), with the narrowing rules of RFC 0005 stated by value.

cargo xtask codec-benchmark is the non-normative decision harness for these profiles. It records size, latency and allocation only after exact semantic, canonical and unknown-data edit fixpoints pass. Native partial loading is a separate capability: profile-0 decoders currently load the complete document. Schema-generated candidates MUST NOT be compared using a partial logical model; the active next-candidate investigation is Cap’n Proto because its encoding specification defines a canonical form. No schema-generated NUIF profile is currently accepted.

The experimental nuif-package-0 profile assigns .nuif to a deterministic ZIP container. Bare encodings use .nuif.json and .nuif.cbor. Historical alpha files that used .nuif for bare bytes MAY be recognized read-only through content detection, but new .nuif output MUST be a package once this profile is accepted.

nuif-package-0 is proposed by RFC 0010. Its reference codec, cross-writer byte fixture, package/resource identity relations, explicit resolver and hostile archive/one-over suite are executable through cargo xtask gate-i-package. The separate nuif-png-rgba8-0 segment is executable through cargo xtask gate-i-image; nuif-opentype-static-single-0 is executable through cargo xtask gate-i-font. This is not full Gate I: broader PNG and OpenType interpretation plus cross-platform/external package and media evidence remain incomplete.

Numeric and string rules (RFC 0005)

• Numeric kinds are integer (signed 64-bit) and real (binary64). Authored reals MUST be finite. Negative zero is not distinct from zero.
• In nuif-cbor-0, integers use major type 0 or 1 and reals use the shortest IEEE 754 floating-point width that round-trips, including integral reals. Integer and real are distinct logical values. Both real zeros use positive floating-point zero; integer zero remains distinct. Integer heads MUST be shortest; lengths MUST be definite; map keys MUST be strictly increasing in bytewise order of their complete deterministic encoding; no tags and no simple values other than false, true and null appear; extension and unknown-kind payloads are byte strings hashed verbatim (RFC 0008).
• Decoders used for hashing and conformance MUST reject non-canonical input rather than re-canonicalize it.
• In nuif-text-0, reals print as the shortest round-trip decimal in the fixed layout of RFC 0005 rule 15; NaN and infinities are parse errors; keys are in UTF-8 byte order; layout is not significant. Text key order is intentionally independent from CBOR encoded-key order (RFC 0008).
• Identifiers (namespaces, keys, kind names, extension names) match [a-z0-9][a-z0-9_.:-]*. String values are stored verbatim as valid UTF-8 and are never normalized by canonicalization.

Hash

The canonical hash of a document is SHA-256 over its nuif-cbor-0 bytes. The text profile has no separate hash: hash(text) = hash(cbor(parse(text))). Published content identifiers carry the profile identifier. Canonical hashes MUST exclude transport-only compression differences.

Package, resource and semantic hashes are distinct:

• document_hash is SHA-256 of canonical document.cbor and covers semantic asset bindings;
• resource_digest is SHA-256 of exact resource bytes;
• package_hash is SHA-256 of the complete deterministic package bytes.

Package-only caches or reports may change package_hash without changing document_hash. Replacing a resource bound to an asset changes the resource digest and semantic document hash while preserving stable AssetId.

Proposed package profile 0

The package member set is:

mimetype
manifest.cbor
document.cbor
blobs/sha256/<digest-hex>

The first member is stored mimetype with exact ASCII value application/nuif+zip. This media type remains provisional until registration. manifest.cbor and document.cbor are canonical nuif-cbor-0.

The manifest declares package profile/version, the canonical document descriptor, required capabilities, stable assets and every immutable resource descriptor. A descriptor includes media type, SHA-256 digest, size, role and an embedded or explicit linked locator. The manifest is not self-addressed.

Required capabilities are a set of at most 256 identifiers, each at most 128 ASCII bytes and matching [a-z0-9][a-z0-9_.:-]*. Structural package decode MUST validate and preserve this set without pretending the host implements it. Before claiming full package support, a host MUST compare the complete set with capabilities it explicitly declares. Missing requirements MUST be returned as an exact deterministic set. Inspection, preservation and migration tools MAY operate after structural decode without claiming full semantic or behavioral support and MUST NOT execute a resource merely because its capability is declared.

Profile 0 uses stored ZIP members only; mimetype is first and other names are bytewise sorted. Names are exact ASCII registered paths. Writers use fixed timestamps/header attributes, no comments/extra fields/data descriptors, encryption, directories, ZIP64 or split archives. The manual reference writer and zip 8.6.0 independently reproduce the exact header fixture.

Readers MUST reject duplicate decoded names, non-ASCII/backslash/absolute/dot paths, directories, symlinks, encryption, unsupported compression, inconsistent headers, unknown members, undeclared blobs, missing required blobs and size/digest mismatches. Readers MUST NOT extract package members to a filesystem.

Portable packages embed every resource required by their declared profile. Linked resources are explicit and never fetched implicitly; a caller-supplied resolver verifies expected size and digest before use. Credentials MUST NOT be stored in resource locators.

Schema versions

Every serialized record kind carries a schema version. Migrations are registered pure functions per kind; reading a record whose version is newer than the implementation knows is an error with a diagnostic, never silent loss.

Parsers MUST enforce resource limits and reject cycles where the relevant graph is specified acyclic. The experimental package limits are 80 MiB per archive, 32 MiB per resource, 64 MiB total embedded resources, 8,192 descriptors and 256 required capabilities of at most 128 bytes each. nuif-png-rgba8-0 additionally limits encoded input to 32 MiB, each dimension to 8,192, pixels to 16,777,216 and chunks to 4,096. nuif-opentype-static-single-0 limits encoded input to 32 MiB, tables to 256, family names to 256, coverage ranges to 65,536 and feature settings to 64. Broader image interpretation and general font-format/policy limits remain experiment-required and MUST be accepted through later media profiles before implementations claim those capabilities.

09 — Provenance, correspondence and fidelity

Document status: draft. Canonical source.

ProvenanceRecord identifies an origin system, source artifact revision and optional source path/range/node/property identity.

CorrespondenceRecord maps NUIF identities/properties to one or more foreign identities/properties and can retain adapter-specific reconstruction hints.

Correspondence is optional canonical-adjacent metadata: it may be stored in a package/profile without changing the semantic document.

Every import/export/lowering returns a FidelityReport with item-level status: lossless, representable, approximated, preserved_unrenderable or unsupported. Diagnostics identify the entity/property and transformation pass responsible.

This mechanism is informed by symmetric and retentive lens research.

Evidence classes

Provenance for capture/reconstruction additionally declares one evidence class:

• authored_source
• resolved_source
• observed_pixels
• inferred
• user_confirmed
• derived
• unavailable

The evidence class and fidelity status answer different questions. Evidence states what was available; fidelity states what was preserved or represented. Confidence states predicted correctness and MUST NOT promote a weaker evidence class to a stronger fidelity claim.

authored_source MAY be lossless only under a declared adapter round-trip profile. resolved_source can be exact for one pinned resolved context without proving authored intent. observed_pixels and inferred MUST NOT be lossless for authored structure, original resources, responsive rules, accessibility or behavior. User confirmation is an additional record and does not erase the original inference history.

A derived record identifies its input digests and exact deterministic or generative transformation. Screenshot crops, traces, inpainting and upscaling are derived resources, never recovered originals.

Confidence and alternatives

Raw provider confidence and calibrated confidence are separate fields. Calibrated confidence identifies a versioned calibration profile and typed correctness event. Whole-document confidence cannot substitute for property- or decision-level confidence.

When evidence is ambiguous, an implementation SHOULD preserve ranked alternatives or abstain. Automatic application MAY be governed by a declared risk/coverage policy; below-threshold values require review or remain unresolved.

Observation identity

An observation records source artifact digest, source region/locator, coordinate space, evaluation context, provider artifact/version, candidate values, evidence class, confidence and privacy/retention class. Coordinate transforms between source pixels, device pixels, viewport pixels, crop-local pixels and NUIF units are explicit.

10 — Collaboration profile

Document status: executable bounded register and existing-tree structural profiles. Canonical source.

Collaboration is operation-based and layered above canonical NUIF.

A collaboration engine MUST be able to materialize a canonical NUIF snapshot without collaboration metadata. Replica IDs, clocks, tombstones and sync-state are profile data.

The profile defines convergence requirements, causal/change identifiers, transaction grouping, awareness/presence separation and checkpoint materialization. It does not mandate Automerge or Yjs.

Semantic conflicts that cannot be merged safely remain explicit conflict objects even if the underlying CRDT converges structurally.

Executable register profile 0

nuif-collab-registers-0 represents each collaboration change as a replica/counter dot, a transitive version-vector context and one semantic operation. The metadata lives in the profile state and is stripped from the materialized Document.

Register-like operations use one multi-value register per entity/property pointer. Causally superseded values leave the frontier. Concurrent distinct values remain in an explicit SemanticConflict; a deterministic selected dot permits a provisional canonical checkpoint without discarding the candidates from the checkpoint report. The operation-set join is commutative, associative and idempotent, and incomplete causal histories fail closed.

Profile 0 supports rename, size, container layout, grid-item placement, token, authored-value, extension-declaration, entity-extension and unknown-payload registers. It rejects insert, remove, move and restore-subtree. Structural collaboration requires a declared tree move/list algorithm, cycle handling and tombstone policy and MUST NOT be inferred from register convergence.

cargo xtask gate-h compares an operation-set maximality materializer with an incremental replica-log frontier materializer over every delivery permutation of the bounded conflict fixture. These are algorithmically separate in-repository implementations, not foreign-engine interoperability evidence.

Executable existing-tree structural profile 0

nuif-collab-tree-0 accepts only Move and Delete for entity identities already present in one validated canonical base. Creation, subtree payloads, relations, property changes and mixed structural/property transactions are not part of this profile. A structural change uses the same dot and transitive version-vector requirements as the register profile. Every engine and joined operation set is bound to the canonical hash of exactly one base; merging different bases is a typed failure. The dot’s total order is (counter, replica).

A move carries (entity, new_parent, anchor). anchor is either Start or a stable position identifier. A base position is Base(entity_id); every move creates Change(dot). An authoring surface MUST resolve a canonical After(entity_id) against its current checkpoint and persist the resulting stable position. It MUST NOT reconstruct a stale anchor from the entity’s current position after synchronization. A Change(dot) anchor MUST name a received change included in the author’s transitive causal context; a missing or non-causal anchor change fails the checkpoint as incomplete history.

The materializer MUST behave as if all changes were applied in ascending dot order:

1. An unknown entity or parent is a typed failure and produces no checkpoint.
2. Moving an entity below itself or its current descendant has no structural effect, remains in the applied history and emits CycleRejected.
3. A missing anchor, an anchor from another parent, or the entity’s own position has no structural effect and emits its typed anchor conflict.
4. A valid move deactivates the entity’s prior position and creates an active position under the target parent. Inactive positions remain as sibling origins.
5. Delete deactivates the prior position and assigns the entity to synthetic profile trash. Descendant relationships are retained in profile state.
6. A later valid move may restore a trashed entity or rescue one of its descendants.

Sibling order is an RGA-style origin traversal. Positions with the same origin sort by descending position identifier, followed recursively by their own descendants. Base sibling order is represented as an origin chain. Position IDs, inactive positions, clocks and trash are profile metadata. The canonical checkpoint stores only ordinary ordered child arrays and removes every entity not reachable from a visible root; it MUST validate and hash as canonical NUIF.

Concurrent distinct moves of one entity, delete/move of one entity, deletion of a destination parent and deletion of a moved entity’s base ancestor MUST remain typed semantic conflicts. Total ordering selects a provisional tree but does not erase those candidates.

Gate H compares full sorted replay with an incremental local/rollback-replay engine for all 5,040 deliveries of the bounded fixture, multiple joins, duplicate delivery and a 4,096-change scaling case. Pinned Automerge 3.4.1 must reproduce the exact immutable operation set through different merge orders and save/load. That foreign check covers convergent transport only; it is not an independent implementation of these tree semantics.

11 — Security and resource limits

Document status: draft. Canonical source.

NUIF documents and extensions are untrusted input.

Implementations MUST bound decoded sizes, nesting depth, entity/relation counts, path segment counts, image/font sizes, decompression ratios and renderer resource allocations. Cyclic references MUST be detected where forbidden.

Executable profile-0 limits

An implementation claiming executable profile-0 conformance MUST accept values at these boundaries and MUST reject the first value above them as a resource-limit error:

Stream readers MUST stop after reading the first byte beyond the encoded limit; reading an entire larger stream and checking afterward is non-conforming. Syntax depth MUST be checked outside quoted strings and comments. Semantic limits MUST be checked before recursive evaluation. Encoders MUST stop before producing the first byte beyond the encoded limit.

Validators MUST retain no more than 1,024 ordinary diagnostics plus one explicit truncation diagnostic. Implementations MAY use tighter operational limits when they are not making a profile-0 conformance claim, but MUST expose those limits to automation.

The reference conformance run measures each boundary and one-over case in a warmed release process. Its regression ceilings are 2 seconds, 64 MiB of allocator traffic and 16 MiB retained per case. These are reference-implementation CI ceilings rather than portable format semantics; the report MUST identify its allocator method, toolchain, build profile and hardware context.

Fonts, images, SVG/imported data, adapters and plugins require sandbox-aware handling. Script/data-binding extensions are non-core and MUST NOT execute merely by opening a document.

Package readers MUST reject duplicate/traversal/absolute/backslash paths, symlinks, directory entries, encryption, split archives, unsupported compression and inconsistent local/central metadata. Implementations MUST verify declared resource size and digest before image/font/media decoding and MUST NOT extract untrusted members to a filesystem.

Loading a package MUST NOT initiate network access. Linked resources require an explicit caller-supplied resolver and exact digest verification. Resource locators and provenance MUST NOT carry cookies, authorization values or other credentials.

Observation providers and model output are untrusted inputs. Reconstruction profiles MUST bound screenshots, observations, candidates, operations, iterations, model/tool calls, renders, time, memory and GPU use. Generated URLs and scripts are inert. Text visible in an image is input data and cannot alter tool authority, security policy or operation grammar.

Screenshot/capture records can contain personal, credential or proprietary information. Retention, remote inference, telemetry and training are separate purposes requiring explicit policy. Private/authenticated captures MUST default to no training.

Headless rendering MUST expose deterministic timeout/memory/resource budgets. GPU failures must not compromise process memory safety.

The experimental live Chromium capture segment runs each page in a fresh temporary profile and accepts only its ws://127.0.0.1 debugger endpoint. It caps one debugger message/frame at 32 MiB, queued events at 65,536 and their aggregate encoded bytes at 64 MiB, commands at 100,000, DOM nodes at 32,768, captured responses at 8,192, one response/screenshot at 16 MiB, total response bodies at 64 MiB, platform-font records at 64 per node and 32,768 total, and the WebSocket write buffer at 1 MiB. Browser startup and protocol I/O each have 10-second bounds, while the connected capture has a 30-second deadline. The discovery HTTP response is capped at 1 MiB and must contain a valid content length. Query/fragment values are removed before serialization; cookie, storage and request-header APIs are never read.

The live conformance fixture accepts only complete captures. A missing response body remains an omission in the adapter result; the harness may retry that viewport in a new isolated profile at most three times and records every attempt. Network response bodies are primary, Page resource content is a post-load fallback, and the canary probe body is retained only after its in-page response completes and is checked for reflected canary values.

Live capture still executes the target page inside Chromium and may cause its declared network behavior. The caller MUST authorize the target and apply network/process isolation appropriate to untrusted content. The experimental adapter MUST NOT import a user’s persistent browser profile or credentials. Exact response bodies can themselves contain sensitive data, so their retention, transfer and training policy remains explicit even when transport canaries are absent.

Image, font, compressed-package, path-segment and GPU budgets are not part of executable CPU profile 0. Orthogonal resource profiles MUST calibrate and publish their own limits before claiming those resource classes.

The orthogonal experimental nuif-png-rgba8-0 image segment publishes a 32 MiB encoded-byte limit, 8,192-pixel limit per dimension, 16,777,216-pixel decoded limit and 4,096-chunk limit. Its inspector applies these bounds before inflation. Render scenes additionally cap unique decoded RGBA surfaces at 64 MiB, preflight each new surface, and deduplicate repeated digest/profile uses. Its two decoders verify datastream integrity. These limits do not authorize other PNG forms, non-PNG media, GPU allocation or inclusion in CPU render profile 0.

The orthogonal experimental nuif-opentype-static-single-0 segment publishes a 32 MiB encoded-byte limit, 256-table limit, 256-family-name limit, 65,536-coverage-range limit and 64-feature-setting limit. It validates sfnt search fields, sorted unique table records, exact contiguous zero-padded packing, per-table checksums and the whole-font checksum before accepting face metadata. Its warmed reference implementation additionally caps one inspection or packaged-font validation at 4 MiB allocator traffic and 2 MiB retained memory. The allocation ceilings are CI regressions rather than portable format semantics. These limits do not authorize other font containers/outlines, native rasterizer execution, redistribution or inclusion in CPU render profile 0.

12 — CLI, API and automation surface

Document status: draft. Canonical source.

A conforming reference implementation MUST expose semantic operations without GUI automation.

Required command classes: inspect, query, validate, canonicalize, diff, patch, render, layout, snapshot, migrate, capabilities, replay, import and export.

Every command MUST support machine-readable output and stable diagnostic codes. Headless commands SHOULD accept stdin/stdout for pipeline use.

The editor MUST route mutations through the same operation layer available to CLI/API clients. AI/MCP adapters are optional clients of this interface and are never the canonical protocol.

The reference in-process SDK profile is a byte-oriented façade over the canonical codecs, package and operation implementation. Bare text/CBOR loading MUST name its encoding; package loading MUST run the complete package/resource validation path. A loaded package MUST retain verified embedded resources and descriptors across neighboring semantic edits. Export to a portable mode MUST rerun the target mode’s resource policy.

Language and process wrappers MAY add transport limits, ownership conversion and host authorization. They MUST NOT copy the semantic model or independently implement validation, canonicalization, hashing, package policy or operation application. Equivalent wrapper calls over the declared common subset MUST produce the same canonical bytes, hash and diagnostics as the direct SDK.

A package-aware wrapper MUST distinguish structural load from full-support negotiation. Structural load MAY preserve or inspect unknown required capabilities, but MUST NOT execute them or claim support. Before evaluation it MUST compare the manifest requirements with an explicit bounded host set and fail with the exact unavailable identifiers. A package-preserving wrapper MUST produce the same deterministic archive bytes as the direct SDK for the same document, resources, capabilities and target mode.

When any requirement is unavailable, a package-aware SDK or wrapper MUST also reject semantic mutation, undo/redo, changed package saves and package-mode conversion atomically. It MAY validate, hash, extract a bare document or copy the unchanged same-mode package. Successful complete-set negotiation MAY authorize mutation and evaluation for that loaded session; a failed partial negotiation MUST NOT do so.

An editor that lacks any required package capability MUST treat the package as read-only unless a capability-specific authoring profile defines how every affected resource is updated or explicitly detached. Structural selection, inspection and exact package copying MAY remain available. A semantic mutation or changed save MUST fail atomically with the unavailable requirement set; silently carrying opaque resources onto a new document revision is forbidden.

A future C ABI is a separate versioned profile. It MUST define opaque-handle lifetime, byte-buffer ownership and release, panic containment, stable error classes, threading, calling convention and exported-symbol compatibility. C, Swift or Kotlin bindings are not claimed merely because a shared library or generated header compiles. Native consumer tests and platform packages are required before integration status.

The experimental nuif-mcp-tools-0 profile is a stateless, stdio-only process adapter for MCP 2026-07-28. It exposes validate, inspect, canonicalize and atomic apply_patch as pure inline-text transforms over the authoritative core. It MUST NOT infer filesystem paths, retain a hidden document session, or gain network, credential, package-resource or host-product authority. Every request is independently bounded and carries current protocol metadata; a client does not perform the retired initialization handshake. MCP tool annotations describe side effects but do not grant authority.

Capture and reconstruction systems are also optional clients. They MUST submit bounded typed transactions through the ordinary operation API, and MUST receive the same validation, stale-revision, atomicity and diagnostic behavior as the CLI/editor. A model/provider cannot gain direct mutation access to internal document structs.

An automation surface supporting reconstruction SHOULD expose distinct commands or calls for observe, propose, evaluate and correct. Every call records input/output hashes, budgets, provider artifact identity and machine-readable diagnostics. Model weights, low-rank adapters, processors and training data are operational artifacts outside the NUIF document and core conformance profile.

13 — Semantics, accessibility and behavior

Document status: exploratory draft. Canonical source.

Semantic role layer

NUIF entities MAY carry semantic roles independently of visual entity kind. The current wire model carries a portable role identifier, one direct accessible name and Boolean state keys. Document relationships can express labelled-by, described-by, controls, owns and flow-to. A direct description string, non-Boolean value/state data and semantic relationship cardinality rules require a future schema revision; adapters MUST NOT invent them from visual geometry.

Adapters MUST map portable semantics to host accessibility facilities where supported and MUST report unsupported or approximated semantics. Visual appearance MUST NOT be treated as sufficient evidence of semantic role.

Web accessibility projection profile 0

nuif-web-accessibility-0 is an experimental bounded lowering to inert HTML and ARIA. It admits at most 4,096 entities and 8,192 relationships. Its role set is button, checkbox, group, img, main, navigation, paragraph, radio, region and switch. Role-specific required/prohibited naming and Boolean-state rules are fixed by the profile. A switch MUST carry checked; unsupported or misplaced states MUST fail closed. A direct accessible name and labelled-by MUST NOT compete on one entity. Direct and referenced names MUST be whitespace-normalized for computed-name comparison and MUST NOT be empty after normalization.

The five relationship kinds above lower to their corresponding ARIA IDREF attributes using stable NUIF entity identifiers. Relationship order is retained and duplicate targets fail closed. The owns graph MUST be acyclic and each owned target MUST have at most one ARIA owner. Native HTML semantics are used where the profile has an exact element; explicit ARIA is used only for group, img and switch. Output contains no script, external URL, event handler or synthesized host behavior.

The foreign oracle MUST record the exact test-engine and host versions, compare computed role/name/state rather than source attributes alone and classify required-subset loss separately from other host-tree differences. Browser-tree agreement does not establish native platform API, keyboard interaction or application behavior equivalence.

Behavior graph

Portable interaction is represented as a separate bounded graph referencing stable entity/property identities. It MUST NOT embed arbitrary general-purpose code. The initial executable research profile is deliberately smaller than the eventual vocabulary of events, state, value transforms, property writes, navigation and animation triggers.

Behavior capabilities are negotiated like extensions. Missing optional capabilities may degrade according to declared fallback; missing required capabilities prevent a claim of behavioral conformance.

Behavior state-machine profile 0

nuif-behavior-state-machine-0 is an experimental sidecar and is not part of the canonical semantic Document model. It defines a flat deterministic state machine with a single active state. Its only external event is activate, addressed to a stable entity carrying role button, checkbox, radio or switch. Transitions in the active state are evaluated in authored order; the first exact event and equality-guard match executes its actions sequentially and selects its target state. An unmatched event is a no-op. An event MUST complete before the next external event is accepted.

Profile values are Boolean or bounded string. Actions may set a value, toggle a Boolean or emit an abstract visibility(Boolean) or announcement(String) effect to a stable entity. The reference runtime MUST NOT directly mutate the document or invoke host APIs. Target adapters consume effects under separately declared capability and fidelity contracts.

Every used effect capability MUST be declared required or optional_noop. A missing required capability MUST reject runtime construction before actions execute. An unavailable optional capability MUST emit no host effect and MUST be recorded as skipped in the trace. Unknown or incompatible entities, states, variables, value types, capabilities, unreachable states and over-limit graphs MUST fail closed before execution.

The profile admits at most 128 states, 1,024 transitions, 4,096 total actions, 64 actions per transition, 128 variables, 64 capabilities and 4,096 external events per run. Timers, internal events, parallel states, numeric computation, navigation, animation, filesystem/network effects and scripts are excluded. Conformance compares complete event, selected-transition, state, variable, effect and skipped-capability traces. Final-state agreement alone is insufficient.

Behavior package resource profile 0

nuif-behavior-package-resource-0 is the experimental transport defined by RFC 0012. It does not change nuif-package-0 or the canonical Document. Exactly one embedded resource MAY carry a behavior program. Its descriptor MUST use role source, no derivation and provisional media type application/nuif-behavior+cbor; its bytes MUST be canonical nuif-cbor-0 for one nuif-behavior-state-machine-0 program. The package manifest MUST also declare nuif-behavior-state-machine-0 as a required capability.

A behavior capability without its resource, a behavior resource without its capability, multiple behavior resources, a linked resource, non-canonical bytes or a program invalid for the package document MUST fail the attachment profile. The program MUST validate against the actual package document both before attachment and after decode.

The resource digest identifies exact behavior bytes; it does not include the document hash. The deterministic package manifest and complete package hash bind the behavior descriptor and document descriptor together. Attachment therefore changes the package hash without changing the semantic document hash. A transplanted resource MUST be revalidated against its new package document.

Generic package decoding MAY verify, preserve and re-encode the inert resource without interpreting it. Full behavioral conformance requires explicit attachment decoding and a separately authorized runtime capability set. Opening, inspecting or preserving a package MUST NOT execute behavior or grant filesystem, network, script or host-mutation authority.

Web behavior projection profile 0

nuif-web-behavior-0 is an experimental one-way composition of nuif-behavior-state-machine-0 and nuif-web-accessibility-0. The complete source profiles MUST validate before host output. The web projection admits activate only for enabled native button elements or the button-backed switch role. Checkbox and radio event sources and disabled transition sources MUST fail closed. Every enabled button/switch in the document MUST be bound so an activation with no matching transition retains the source profile’s no-op semantics. A visibility effect MUST NOT hide an admitted event source or its containing ancestor because later native activation would become impossible.

visibility(Boolean) MUST map to the target HTML element’s hidden property. A non-empty announcement(String) MUST map to the text of one unfocused status live region with polite, atomic semantics and retain its stable target identity as observation metadata. A transition MUST NOT emit more than one announcement or repeat the same effect-kind/target pair because a single host task may collapse those abstract effects into one observation.

The generated output MUST contain only a fixed finite interpreter plus the validated program as escaped data. Program strings MUST NOT terminate the script element. Arbitrary authored script, handler attributes, evaluation, dynamic import, timers, network and filesystem authority are prohibited. A self-contained document MUST restrict the exact runtime by a content hash and deny every unneeded resource class. A serving host SHOULD deliver its own response-header Content Security Policy and MUST NOT assume a nested document’s policy transfers to the host page.

Conformance MUST drive native activation and compare selected transition, target state and retained host effects after every event through each declared engine. DOM and browser accessibility-tree observations do not establish assistive-technology speech, focus behavior or native platform UI equivalence.

Host logic boundary

Application business logic, arbitrary network effects and unrestricted scripts are outside the core document model. Adapters may preserve references/bindings to host logic using extensions and provenance, but another implementation is not required to execute unknown host code. The state-machine sidecar MUST NOT be interpreted as authority to execute such bindings.

Inference

Behavior inferred from screenshots or static design states is never lossless solely because the generated result looks equivalent. Inference records MUST identify evidence, confidence and unresolved alternatives.

14 — Observation, capture and reconstruction

Document status: draft. This module specifies candidate contracts from RFC 0011. No. Canonical source.

screenshot reconstruction profile is currently conforming. The fixed-input contract baseline exercises observation/proposal encoding, evidence ceilings, manifest-bound providers, flat-copy rejection and bounded correction stops. The separate nuif-cdp-live-0 baseline exercises one pinned, local Chromium fixture; it is not a cross-browser capture or reconstruction-accuracy conformance profile.

Scope

This module covers evidence captured from a runtime or image and the production of a validated NUIF hypothesis. It does not standardize a model architecture, provider, training library, dataset or inference service.

An implementation MUST distinguish:

• deterministic parsing of retained authored source;
• resolved observations from a pinned runtime context;
• measurements of pixels;
• inferred semantic/layout/resource hypotheses;
• explicit user confirmations;
• derived resources/values;
• unavailable evidence.

Observation record

An observation contains:

Every observation bundle MUST carry the exact canonical provider manifest for each referenced identity. Missing, duplicate, malformed or digest-mismatched manifests fail the complete bundle. A proposal provider MUST resolve through the same registry before any operation is applied. An observation MUST NOT imply that its candidate is already a semantic document value. Applying a candidate requires an operation and validation.

Coordinate spaces include source pixels, device pixels, viewport CSS pixels, crop-local pixels and NUIF logical units. A conversion MUST record source and target spaces, matrix/scale/offset and rounding behavior.

Source-backed browser capture

A browser capture profile records browser/protocol build, operating system, viewport, device-pixel ratio, page scale, locale, timezone, media preferences, font environment, scroll/pseudo state, navigation identity, settling policy and animation/time freeze.

The first proposed Web capture observes, where available:

• retained HTML/CSS response bytes and stylesheet text;
• DOM including iframes/templates/shadow content visible to the protocol;
• resolved layout boxes, inline text boxes and paint order;
• declared computed and matched styles;
• downloaded resource bodies, final URLs, response media types and hashes;
• platform-font usage and font-readiness state;
• accessibility tree;
• reference screenshot and capture parameters.

Unavailable cross-origin responses, local font bytes, canvas/WebGL semantics, video state, worklet output and arbitrary script behavior MUST be explicit. Canvas/video output MAY be frozen as a bounded derived image/frame. Captured scripts remain inert resources.

The capture MUST exclude cookies, authorization headers, credentials, storage values and secret form fields from its output. Redaction is a recorded transformation, not silent source equivalence.

The implemented live baseline records a bounded string map as nuif-browser-runtime-context-0 in the observation bundle. It fixes exact browser and reported protocol, operating system/architecture, viewport/DPR, locale, timezone, screen media, color scheme, reduced-motion preference, scroll origin, settling policy and animation policy. Context keys are identifiers, the map is limited to 64 entries and all names/values share the observation string-byte limits. A consumer MUST NOT assume equivalence between bundles with different contexts.

nuif-cdp-live-0 uses an isolated temporary browser profile, accepts only a loopback debugger socket, waits for the lifecycle load event belonging to the exact navigation loader, fixes animation/transition and scroll state, waits two animation frames, awaits font readiness and waits two final frames. It normalizes opaque browser node identifiers before export and strips URL query/fragment data twice: before live capture serialization and again during observation normalization. The gate exercises query, cookie, storage, authorization and custom-header canaries; this proves those declared ingress paths are not retained, not that arbitrary response bodies contain no sensitive application content.

The first implementation observes element layout rectangles, a bounded background-style subset, text, containment/order, downloaded response bodies, actual platform-font use, accessibility role/name and a viewport screenshot. Inline text boxes, complete paint ordering, matched-rule/source-map correspondence, opaque cross-origin bodies, canvas/video derived-frame capture and general interaction states remain outside this automated segment and MUST NOT be inferred from its passing report.

Screenshot-only reconstruction

A screenshot-only implementation receives one or more image/context pairs and MAY run replaceable OCR, computer-vision, grounding and proposal providers. It MUST normalize their output into observations before semantic application.

The proposal engine emits only operations permitted by its declared operation grammar and profile. It MUST NOT emit executable code, implicit network actions or direct core-memory mutations.

Every proposal is applied transactionally:

1. parse under operation/resource budgets;
2. validate operation kinds and expected revision;
3. apply atomically;
4. validate the complete document;
5. evaluate declared layout/render contexts;
6. return a result or leave the prior document unchanged.

A valid screenshot reconstruction includes its accepted operation log, observations, fidelity report, alternatives/abstentions, evaluation report and pipeline artifact manifest.

Screenshot evidence cannot establish original font/image bytes, hidden entities, authored layout constraints, responsive rules, accessibility or behavior. These values remain inferred, substituted, derived or unavailable.

Multi-context inference

When multiple viewports/states are supplied, proposed semantic identity links the corresponding observations. Candidate layout families/constraints SHOULD be ranked by prediction of a held-out context. Fit to every supplied pixel does not prove original authored intent.

An implementation claiming responsive reconstruction MUST evaluate at least one context not used to fit the candidate and MUST report its error separately.

The bounded nuif-layout-inference-0 experimental profile accepts two through sixteen strictly increasing training viewports, one untouched held-out viewport and no more than 4,096 ordered items with stable identities. It ranks row stack, column stack, Grid, linear constraint and fixed-parent-relative freeform candidates by training observations only. The held-out observation is a falsification oracle and MUST NOT influence selection. Its report retains all five alternatives, training score, held-out error, raw confidence and the exact geometry observation identities used for fitting. Confidence is not calibrated and the selected value remains inferred; neither a low error nor the selected family establishes original authored intent. Geometry and identity drift fail closed. The profile is a deterministic geometric baseline, not a general breakpoint, intrinsic-sizing, wrapping or layout-program synthesizer.

Correction loop

A profile MAY iteratively render and correct. Each iteration records:

• input document hash and revision;
• proposed transaction and diagnostics;
• resulting document hash;
• render context and raster hash;
• property-level and visual differences;
• objective vector and protected metrics;
• accept/reject reason.

The loop MUST bound iterations, provider/tool calls, time, memory and resources, and MUST stop on repeated state. Accepted corrections preserve validity and declared semantic non-regression constraints.

An editable reconstruction objective MUST reject a viewport-sized copy of the source screenshot as success unless a flat image document was explicitly requested.

Evaluation

Reports separate source-backed capture from screenshot-only reconstruction. Required metric families for an editable screenshot profile are:

• valid transaction/document rate;
• text-region precision/recall, character/word error and baseline geometry;
• visible-element precision/recall;
• tree/parent/sibling correctness where a target is justified;
• property and geometry error;
• held-out-context layout error;
• exact resource-digest recall only where source bytes are supplied;
• provenance/fidelity honesty;
• accessibility evidence accuracy where a target is justified;
• raw pixels plus declared perceptual diagnostics;
• calibrated confidence, abstention and risk/coverage;
• latency, peak RAM/VRAM, iterations and external cost.

The executable nuif-reconstruction-evaluation-0 report implements these as typed, bounded per-example fields in crates/nuif-reconstruct/src/evaluation.rs. Rates retain their integer numerator and denominator; a zero denominator serializes with no value and is never treated as perfect. Unavailable RAM/VRAM or latency measurements remain null rather than zero. Screenshot-only suites MUST leave exact source-resource recall unscored. cargo xtask reconstruction-evaluation exercises the schema, derived-value validation, resource-claim boundary, local-error visibility and hostile work limits. Its typed corpus aggregate refuses mixed evidence suites, duplicate examples, incompatible calibration thresholds, perceptual evaluator identity drift and mixed currencies. It reports pooled integer-evidence rates beside per-example scored/unscored counts, mean and nearest-rank p50/p95. This synthetic contract fixture is not an accuracy corpus or a confidence interval. Every perceptual entry also carries a bounded parameter map and optional content digest identifying the evaluator artifact. Aggregation is permitted only when method, direction, parameters and artifact identity agree. The current diagnostic is LDR-FLIP mean at a declared 67 PPD over opaque sRGB8; transparent input MUST be composited against a declared background before evaluation, never silently discarded.

No visual metric alone establishes conformance. Metrics are reported per example and as distributions; local/small-element errors MUST NOT be hidden by a large background average.

Synthetic exact fixtures and licensed/human-reviewed real fixtures are separate corpora. Splits MUST prevent origin, template, component, font, resource, generator and near-duplicate leakage. Benchmark families MUST NOT appear in adaptation or distillation data.

nuif-reconstruction-corpus-manifest-0 is the executable integrity contract. It content-addresses the immutable data snapshot, dataset card, evaluator, inputs and targets; separates public, restricted and withheld artifacts; and records collection class, rights evidence, permitted evaluation/calibration/ adaptation/redistribution uses, sensitivity review and leakage groups per example. Its derived nuif-reconstruction-corpus-audit-0 rejects identities shared across any distinct adaptation, calibration, validation or test split. Screenshot-only records cannot carry exact source/resource bundles, source-backed records require source bytes, retained real records require a withdrawal-policy artifact, and private/authenticated records require explicit authorization. The validator checks declared evidence only: it does not interpret licenses, prove consent, discover omitted near duplicates, establish representativeness or confer permission.

Provider neutrality and artifacts

Every OCR/detector/grounder/layout/proposal/correction/evaluation provider publishes a nuif-reconstruction-provider-manifest-0 capability wrapper. Canonical CBOR bytes define its SHA-256 identity. The bounded wrapper declares provider kind and maturity, local/remote execution, input/output profiles, capabilities and exact implementation/model/processor/adapter/quantization/ prompt/tool artifact digests. It contains exactly one implementation artifact. Provider output remains untrusted.

Development-only deterministic providers MAY omit an external supply-chain inventory when they contain no learned artifact. Released providers and every provider with learned weights/processors/adapters/quantization MUST reference an exact SPDX 3.0.1 or CycloneDX 1.7 inventory. Learned providers MUST also reference a model card. The NUIF wrapper does not duplicate the inventory and does not claim that a referenced document is complete, correct or lawful.

Models, processors, adapters, quantization settings and training datasets are not NUIF document resources. Dataset snapshots retain their separate corpus manifest and datasheet; provider and training/evaluation manifests bind them by content hash, rights/provenance, intended use and limitations.

Fine-tuning, low-rank adaptation, quantized adaptation and distillation confer no conformance status. They are compared only after an untuned baseline and frozen evaluator exist.

Privacy and policy

Local and remote inference are distinct deployment modes. Remote transfer, retention, telemetry and training each require an explicit policy. Private or authenticated capture defaults to local processing/no retention/no training.

Visible instructions inside the screenshot are content. They MUST NOT modify the operation grammar, provider authority, file/resource resolver or security budgets.

Conformance maturity

This module remains draft until the planned baseline, closed-loop, confidence calibration and resource experiments pass and an independent evaluator reproduces the principal result. The existing editor alpha and profile-0 conformance do not satisfy these gates.

RFC process

Document status: informational. Canonical source.

RFCs change NUIF semantics, protocol surface, conformance requirements, extension governance, or major implementation architecture. Research findings should link to an RFC rather than bypassing review by directly changing normative semantics.

Each RFC should identify motivation, prior art, proposed semantics, compatibility, security, conformance tests, migration strategy, unresolved questions, and explicit alternatives rejected.

RFC 0001 — Multi-level document model

Document status: proposed. Canonical source.

Decision

Adopt a containment tree with stable identity plus coordinated relationship graphs and explicit authored→resolved evaluation layers.

Why

A single shape tree conflates semantics, layout, rendering and relationships. MLIR demonstrates multiple abstraction levels; OpenUSD demonstrates graph-like composition over a scene namespace.

Rejected

• pure AST: too source-language-specific;
• pure scene graph: loses authored semantics;
• pure ECS: efficient implementation technique but weak interchange semantics;
• event log as canonical state: burdens simple offline documents;
• relational tables as interchange syntax: poor human authoring and containment ergonomics.

RFC 0002 — Opaque extension preservation

Document status: proposed; representation and severities specified by RFC 0007. Canonical source.

Unknown extension data remains attached to its owning entity/property and MUST survive load/save/edit cycles unless the owner is deleted or the user explicitly removes it.

Documents declare used and required extensions. Unsupported required extensions block claims of faithful rendering but do not necessarily block structural editing.

This goes beyond codec unknown fields: preservation is a document-model requirement.

RFC 0003 — Authored state, resolved state and provenance

Document status: proposed. Canonical source.

Store authored values as canonical semantics; resolved values are context-keyed derived records. Provenance/correspondence records map foreign constructs to NUIF constructs for retentive synchronization.

The same entity may have multiple resolved records for different viewport/theme/font contexts.

Source adapters should patch original syntax trees using correspondence and structured edits instead of regenerating whole files.

RFC 0004 — Headless QA contract

Document status: proposed. Canonical source.

Every meaningful reference-editor action must be expressible through semantic operations and inspectable via CLI/API. Tests must be able to create fixtures, execute operations, compute layouts, render deterministic snapshots, query semantic/accessibility trees and replay failures without mouse-coordinate automation.

An AI QA agent is therefore just one client of a stable automation contract.

RFC 0005 — Deterministic numeric and string canonicalization

Document status: accepted (decision delegated to research on 2026-08-29; evidence in nuif:research:deterministic-cbor-profiles-and-numeric-canonicalization, nuif:research:ipld-dag-cbor-strictness, nuif:research:canonicalization-rfc8785-and-cbor-deterministic). Canonical source.

Correction: RFC 0008 supersedes rules 6 and 8 and the key-order coincidence claim in rule 17. Integer and real values remain distinct in nuif-cbor-0; readers must apply RFC 0008 when implementing this RFC.

Motivation

spec/08-serialization.md requires byte-stable canonical hashes for nuif-cbor-0 and nuif-text-0 but leaves numeric normalization, map ordering and string rules undefined. The IETF CBOR working group’s Common Deterministic Encoding draft (draft-ietf-cbor-cde) was parked on 2025-10-19 for lack of consensus and expired on 2026-04-16 without an RFC; its successor, draft-ietf-cbor-serialization (revision 08, 2026-07-29, Standards Track, in working-group last call), preserves the data model and is silent on negative zero and duplicate keys. The individual draft dCBOR (revision 18, 2026-08-10) narrows the data model (integral floats become integers, all zeros become 0x00, one NaN, NFC strings, strict decoders) and is not working-group adopted. NUIF must state its rules by value so that neither draft’s future changes alter NUIF hashes.

Prior art

RFC 8949 §4.2 (core deterministic encoding requirements and the list of decisions left to protocols); RFC 8949 erratum 8589 (NaN sign bit in key equivalence); RFC 8785 (JSON Canonicalization Scheme: ECMAScript shortest number serialization, -0 to 0, NaN and Infinity rejected); IPLD DAG-CBOR (strict codec: shortest floats, no NaN or Infinity, no indefinite lengths, content identifiers carry the codec identifier); Automerge’s binary change format (hash over a defined byte layout); glTF JSON and GLB (same document, two containers, no cross-container hash equivalence claimed).

Decision

Logical numeric model

1. The logical model has two numeric kinds: integer (signed 64-bit) and real (IEEE 754 binary64). There is no 32-bit real kind in the model; adapters convert.
2. An authored real property MUST NOT hold NaN, positive infinity or negative infinity. Validation rejects such values at set time with a diagnostic. Resolved snapshots MAY carry non-finite values only inside diagnostics, never as resolved geometry.
3. Negative zero has no distinct identity in the logical model: -0.0 and +0.0 are the same value and canonicalize identically.

nuif-cbor-0

4. The base profile is draft-ietf-cbor-serialization §4.1 (preferred serialization: shortest integer heads, definite lengths only, shortest float width that preserves the value including subnormals, the single NaN encoding 0xf97e00, no bignum tags for values within the 64-bit range) and §5.1 (map keys sorted by bytewise lexicographic order of their encoded form). NUIF cites these sections by name and restates every rule it depends on below so that a change in the draft does not change NUIF.
5. Integers encode as major type 0 or 1 with the shortest argument. Values outside [-2^63, 2^63-1] are invalid for integer properties; the wire range beyond that is never produced.
6. Superseded by RFC 0008: a real remains a floating-point data item even when integral. Decoding never depends on an external property schema to restore numeric kind.
7. A real that is not integral MUST be encoded as the shortest of half, single or double precision that round-trips the value exactly. Subnormals are preserved.
8. Superseded by RFC 0008: both real zeros encode as positive half-precision floating zero; integer zero remains 0x00.
9. NaN and infinities never occur in canonical documents (rule 2). If a future property type admits them, the encoding is 0xf97e00 for NaN and the shortest-width infinity.
10. Simple values other than false, true and null are not used. No tags appear in the canonical body.
11. Map keys MUST be in strictly increasing bytewise lexicographic order of their encoded form; a duplicate key is invalid.
12. Decoders used for hashing or conformance MUST be strict: any deviation from rules 4–11 is rejected with a diagnostic. Decoders MUST NOT re-canonicalize accepted input silently; a lenient import path MAY exist for foreign data and MUST report approximated when it rewrote bytes.
13. Extension payloads and unknown-kind payloads are CBOR byte strings and are hashed verbatim; the container decoder never inspects their content. Tag 24 (embedded CBOR) is not used because it requires well-formed content.

nuif-text-0

14. The text profile is a lossless surface syntax over the same value set. Its canonical hash is defined as the hash of the nuif-cbor-0 encoding of the parsed document: hash(text) = hash(cbor(parse(text))). No separate text hash exists.
15. Reals print as the shortest decimal digit string that round-trips to the same binary64 value (Rust core::num::flt2dec shortest mode is a conforming implementation), laid out as plain decimal when 10^-6 <= |v| < 10^21 and otherwise as d.ddde±x. Integral reals print without a fraction. -0 is never printed. NaN, inf and -inf are parse errors.
16. Integers print in decimal without leading zeros or a plus sign.
17. Map keys in nuif-text-0 are written in UTF-8 byte order. RFC 0008 corrects the earlier claim of coincidence: CBOR encoded-key order differs when key lengths differ.
18. Whitespace, comments and key quoting styles are not significant and are not preserved; the text encoder emits one fixed layout.

Strings and identifiers

19. Namespaces, property keys, extension names and entity kind names are identifiers restricted to [a-z0-9][a-z0-9_.:-]*. They are compared bytewise.
20. String property values (names, text content, token names) are stored verbatim as valid UTF-8 and are never normalized by canonicalization. Rationale: retentive synchronization and minimal source patches require byte-exact preservation of authored text; Unicode normalization is idempotent but not the identity, and applying it would rewrite user text. Adapters that must compare strings semantically compare NFC forms without altering stored values. The validator emits an informational diagnostic for identifiers or token names that are not in NFC.
21. Invalid UTF-8 is a decoding error, not a repairable condition.

Hash

22. The canonical hash of a document is SHA-256 over the nuif-cbor-0 bytes of the document record. Published content identifiers carry the profile identifier (nuif-cbor-0) so that a future profile cannot collide silently.
23. Resolved snapshots and correspondence records are hashed separately under the same rules and are never part of the document hash.

Compatibility

No documents exist yet. Decoders implementing RFC 8949 §4.2 accept the structural subset of nuif-cbor-0 output. dCBOR is not wire-compatible with RFC 0008 integral real values or with NUIF’s verbatim-string rule and is not a NUIF decoder.

Security

Strict decoding removes canonicalization ambiguity as an attack surface (two byte sequences for one value). Extension payloads are opaque bytes with a declared size limit enforced by the parser (spec/11-security.md). RFC 0008 keeps numeric kind self-describing, so generic decoding does not depend on a property schema.

Conformance tests

• canonicalization suite: encode, decode, encode fixpoint; hash stability across platforms; every rule 4–13 has a positive and a negative fixture (non-canonical inputs rejected by the strict decoder).
• numeric fixtures: subnormals, 2^53 ± 1, integral reals remaining floats at the 2^63 boundary, both real zeros canonicalizing to positive floating zero, and shortest-width selection for half and single precision (RFC 0008).
• text fixtures: layout switch at 10^-6 and 10^21; 5e-324 prints as 5e-324; parse rejection of NaN and inf.
• dCBOR §7 test vectors for the rules NUIF shares, with the divergent cases (NFC) marked as intentionally not shared.

Implementation

nuif-codec converts Serde values to ciborium::Value, recursively rejects forbidden values, sorts map entries by encoded key bytes and uses Ciborium’s shortest-width writer. Strict decoding retains the value tree, re-encodes it and compares the original bytes before deserializing the document. This supplies the ordering/checking layer Ciborium intentionally omits while preserving numeric kind under RFC 0008.

Rejected alternatives

• Adopt dCBOR by reference: an individual draft with strict-reject semantics on NFC that would rewrite user text and can change under NUIF.
• Adopt draft-ietf-cbor-serialization by reference alone: silent on negative zero and duplicate keys; NUIF must state both.
• Preserve negative zero as distinct: rejected because the logical model equates the two real zeros. Preserve float/integer distinction: accepted by RFC 0008 because the logical model distinguishes those kinds.
• Separate text hash: two hashes for one document invite inconsistency; the text profile is a view.
• NFC-normalize string values: violates verbatim preservation required by RFC 0003 and the minimal-patch requirement.
• Use JSON with RFC 8785 as the binary profile: no byte strings, no integer/real distinction, larger payloads.

Unresolved

• Whether Rust’s shortest-digit algorithm and ECMAScript Number::toString ever differ in tie-breaking (no counterexample found; irrelevant to NUIF hashes because the text profile hashes through CBOR).
• Whether the text surface remains canonical JSON or adopts a purpose-built syntax after reviewability trials; hashes are unaffected because text hashes through CBOR.

RFC 0006 — Sibling order: canonical arrays and anchored operations

Document status: accepted (decision delegated to research on 2026-08-29; evidence in nuif:research:list-ordering-fractional-indexing-vs-list-crdts, nuif:research:crdt-tree-move-operation, nuif:research:figma-multiplayer-and-rendering-engineering). Canonical source.

Motivation

nuif-protocol expresses Insert and Move with an integer index. Integer positions are not commutative under independent edits, make replay order-sensitive, and cannot be merged without renumbering. The collaboration profile (spec/10) needs positions that converge; the canonical document (ADR 0005) must not carry replica metadata.

Prior art

OpenUSD stores resolved child order as an array and expresses authored reordering as sparse reorder list operations composed at index time (pcp/composeSite.cpp). Figma uses fractional string keys per child, deduplicated server-side, and reports key growth and interleaving as known costs. Automerge and RGA insert relative to a neighbour identifier. Penpot’s change log names an after-shape. Fugue (Weidner and Kleppmann 2023) is the list CRDT with proved forward and backward non-interleaving; Logoot and LSEQ interleave; the PaPoC 2019 interleaving anomaly definition is unsatisfiable per the Fugue paper.

Decision

Canonical form

1. A canonical document MUST represent sibling order as an ordered array of entity identifiers (Entity.children) with no duplicates. It MUST NOT carry order keys, tombstones, replica identifiers or timestamps.
2. Integer indices are a resolved view computed from the array; they never appear in canonical state or in operations.

Operations

3. Insert and Move MUST specify position as an anchor: Anchor::Start or Anchor::After(EntityId).
4. An anchor MUST refer to a current child of the target parent at application time; otherwise the operation fails with the typed conflict AnchorMissing, and patch application reports it.
5. A Move whose target parent is the moved entity or one of its descendants MUST fail with CycleRejected.
6. Within one patch, insertions at the same anchor are applied in patch order.
7. Preconditions MAY assert ParentIs { entity, parent } and Follows { entity, anchor }.

Merge

8. In three-way merge, insertions from different branches at the same anchor are ordered by declared branch precedence and emit the informational conflict OrderAmbiguous listing the entities.
9. Concurrent moves of one entity to different positions produce MoveConflict carrying both targets; a profile MAY converge on one, but the conflict object MUST be retained until resolved.

Collaboration profile

10. A collaboration profile maps anchored operations onto a list CRDT that satisfies forward non-interleaving (Fugue Definition 2) and SHOULD satisfy maximal non-interleaving. Tree moves follow the undo/redo algorithm of Kleppmann et al. 2021 with cycle rejection.
11. Checkpoint materialization MUST emit the plain array of rule 1.
12. Fractional keys MAY be used as profile-internal transport and MUST NOT appear in nuif-core types or canonical hashes.

Type changes (nuif-protocol, signatures only)

#![allow(unused)]
fn main() {
pub enum Anchor { Start, After(EntityId) }

pub enum Operation {
    Insert { parent: Option<EntityId>, anchor: Anchor, entity: Entity },
    Move { entity: EntityId, new_parent: Option<EntityId>, anchor: Anchor },
    // Remove, Rename, SetExtension unchanged
}

pub enum Precondition {
    ParentIs { entity: EntityId, parent: Option<EntityId> },
    Follows { entity: EntityId, anchor: Anchor },
}

pub enum Conflict {
    AnchorMissing { entity: EntityId, parent: Option<EntityId>, anchor: Anchor },
    CycleRejected { entity: EntityId, new_parent: EntityId },
    MoveConflict { entity: EntityId, targets: [(Option<EntityId>, Anchor); 2] },
    OrderAmbiguous { parent: Option<EntityId>, anchor: Anchor, entities: Vec<EntityId> },
}
}

Entity.children: Vec<EntityId> is unchanged and documented as the canonical order with a no-duplicates invariant.

Compatibility

No persisted documents exist. Adapters that import index-based formats compute anchors from the imported order.

Security

Anchor resolution is O(children); cycle rejection is a parent-chain walk bounded by the depth limit in spec/11.

Conformance tests

• operations suite: independent inserts under different parents commute to identical hashes; AnchorMissing and CycleRejected fixtures; replay of anchored logs is deterministic.
• merge suite: same-anchor concurrent inserts produce OrderAmbiguous with branch-precedence order; concurrent moves produce MoveConflict; Kleppmann’s concurrent-move test cases (cycle-forming pair) converge without cycles.
• collaboration experiment: two profile engines converge to the same checkpoint array and no interleaving of two concurrent runs of sequential inserts (Fugue forward non-interleaving check).

Rejected alternatives

• Integer index in operations: non-commutative; order-sensitive replay.
• Fractional keys in the canonical form: history-dependent hashes, unbounded key growth at one gap, jitter randomness, interleaving, no rebalancing procedure documented by Figma or rocicorp.
• List-CRDT identifiers in the canonical form: require tombstones and replica metadata, contradicting ADR 0005.
• Logoot or LSEQ positions in the profile: interleave under concurrent sequential inserts.

Unresolved

• Branch precedence for rule 8 is a merge-policy parameter, not derivable from sources.
• Whether the profile adopts Fugue or FugueMax (and how Yjs YATA’s ordering compares) is settled by the collaboration experiment.

RFC 0007 — Unknown entity kinds and opaque payloads

Document status: accepted (decision delegated to research on 2026-08-29; evidence in nuif:research:unknown-schema-preservation-strategies, nuif:research:opentimelineio, nuif:research:godot-tscn-scene-format, nuif:research:openusd-composition-and-crate, nuif:research:gltf-validator-and-sample-assets). Extends RFC 0002. Canonical source.

Motivation

RFC 0002 requires unknown extension data to survive load, save and edit. It does not define how an entity whose kind is unknown is represented, which operations remain valid on it, how it lays out and renders, or how validation severities are assigned. Godot preserves unknown node classes as placeholders that record the original class and properties and write them back; OpenTimelineIO preserves unknown schemas with name, version and raw payload while still decoding nested known objects; Blender ignores and cannot re-save unknown data; OpenUSD keeps unknown typeName as metadata with fallbackPrimTypes; glTF gates by extensionsUsed and extensionsRequired with validator codes UNDECLARED_EXTENSION (error) and UNSUPPORTED_EXTENSION (information).

Decision

Representation

1. An entity whose kind namespace, kind name or schema version is not supported MUST be loaded as EntityKind::Unknown, retaining namespace, kind name, schema version and the kind-specific payload bytes. A known kind whose schema_version exceeds the implementation’s support MUST also load as Unknown, never fail.
2. Core fields (identifier, name, children, nuif-namespace properties, relations, extensions) of an unknown entity remain typed and editable. Only the kind-specific payload is opaque.
3. Every containment slot MUST admit Unknown.

Operations

4. Remove, Move, Rename, SetExtension, RemoveExtension and core-property operations MUST apply to unknown entities unchanged.
5. SetUnknownPayload is valid only when the applying implementation declares the payload’s namespace; other implementations MUST reject it with a diagnostic.

Preservation

6. An implementation that does not declare a namespace MUST preserve that namespace’s payloads byte-for-byte. An implementation that declares the namespace MAY re-encode deterministically (value-for-value). RFC 0002’s “byte/value-for-byte” language is read as these two cases.
7. In nuif-cbor-0, opaque payloads are CBOR byte strings; the declared encoding (Cbor or Octets) is a sibling field, not a CBOR tag (RFC 0005 rule 13 forbids tags in the canonical body). Hashing covers the bytes. nuif-text-0 encodes the bytes losslessly.
8. A malformed opaque payload yields a diagnostic on the owning entity and MUST NOT invalidate the document.
9. Lowering, flattening and codec conversion MUST carry Unknown entities and extension payloads through; a conformance fixture asserts byte identity after an edit cycle through an implementation that declares neither the kind nor the namespace.

Evaluation

10. Layout treats an unknown entity as the kind named by the document’s fallback_kind declaration for its namespace, else as Container with its authored size intents.
11. Rendering of an unknown entity reports PreservedUnrenderable { namespace, entity } and draws nothing for the kind-specific payload; children render normally.

Validation severities

12. A namespace present in the document but absent from extensions_used: error.
13. A namespace declared in extensions_used and unsupported by the implementation: information.
14. A namespace declared in extensions_required and unsupported: blocks claims of faithful rendering and export fidelity above preserved_unrenderable; MUST NOT block structural editing.

Type changes (nuif-core, signatures only)

#![allow(unused)]
fn main() {
pub enum OpaqueEncoding { Cbor, Octets }
pub struct OpaquePayload { pub encoding: OpaqueEncoding, pub bytes: Vec<u8> }
pub struct UnknownKind { pub namespace: String, pub kind: String, pub schema_version: u32, pub payload: OpaquePayload }
pub enum EntityKind { /* existing variants */ Unknown(UnknownKind) }
pub struct Extensions(pub BTreeMap<String, OpaquePayload>);
pub struct ExtensionDeclarations { pub used: BTreeSet<String>, pub required: BTreeSet<String>, pub fallback_kind: BTreeMap<String, EntityKind> }
pub enum Fidelity { /* existing */ PreservedUnrenderable { namespace: String, entity: Option<EntityId> } }
}

nuif-protocol: SetExtension { entity, namespace, payload: OpaquePayload }, RemoveExtension { entity, namespace }, SetUnknownPayload { entity, payload: OpaquePayload }.

Compatibility

Existing Extensions(BTreeMap<String, Vec<u8>>) gains the encoding field; no documents exist.

Security

Payload size and count are bounded by parser limits (spec/11); payloads are never interpreted by implementations that do not declare the namespace, so untrusted content in them cannot reach an interpreter.

Conformance tests

• extensions suite: decode with an ignorant implementation, apply Rename, Move, SetExtension on neighbours and on the unknown entity itself, encode, assert byte identity of the unknown payload and restoration of the original kind name and version by a knowing implementation.
• validation suite: fixtures for severities 12–14.
• layout suite: unknown entity with fallback_kind and without.

Rejected alternatives

• Silent drop (pre-3.5 proto3 behaviour, Blender): the failure NUIF exists to prevent.
• Host-typed re-encoding of unknown properties (Godot Variant): changes bytes in an ignorant implementation.
• Hard failure on newer schema versions (OpenTimelineIO): prevents structural editing of otherwise valid documents.
• CBOR tag 24 for declared-CBOR payloads: tags are forbidden in the canonical body by RFC 0005, and tag 24 requires well-formed content, which rule 8 does not.

Unresolved

• Whether fallback_kind may name a kind from another extension namespace (transitive fallback) is deferred until a second dialect exists.

RFC 0008 — Preserve numeric kinds and distinguish text/CBOR key order

Document status: accepted (corrective; primary evidence in nuif:research:cbor-data-model-and-key-order-correction). Supersedes RFC 0005 rules 6 and 8 and the coincidence claim in rule 17. All other RFC 0005 rules remain in force. Canonical source.

Motivation

RFC 0005 made integral real values use CBOR integer encodings and required a property schema to restore the type. The NUIF logical value model, extensible properties and unknown data do not guarantee that such a schema is available. RFC 8949 §2 also defines integer and floating-point data items as distinct. The previous rule therefore made a generic lossless decoder impossible and caused integer(1) and real(1.0) to collide.

RFC 0005 also stated that UTF-8 key order coincides with CBOR encoded-key order for NUIF identifiers. It does not: complete CBOR key encodings include a length head, so "z" (61 7a) sorts before "aa" (62 61 61) in deterministic CBOR while UTF-8 sorts "aa" first.

Decision

1. integer and real remain distinct logical values in every encoding and in canonical hashes.
2. An integer uses CBOR major type 0 or 1 with the shortest argument.
3. A finite real, including an integral real, uses the shortest IEEE 754 half, single or double CBOR floating-point encoding that round-trips exactly.
4. Negative real zero has no distinct NUIF identity and encodes as positive half-precision floating-point zero (f9 00 00). Integer zero encodes as 00. This replaces RFC 0005 rule 8.
5. Maps in nuif-cbor-0 sort by bytewise lexicographic order of each key’s complete deterministic CBOR encoding.
6. Objects in nuif-text-0 sort string keys by UTF-8 byte order. Text and CBOR key order need not coincide because the canonical document hash is computed from parsed nuif-cbor-0, not text bytes.
7. A decoder used for conformance or hashing rejects an integral real encoded as an integer when the surrounding NUIF value discriminant says real; it does not infer or repair the lost kind.

Compatibility

No published documents exist. The profile identifier remains nuif-cbor-0 because the prior rules had no implementation or fixtures; the first executable codec implements this RFC.

Security

Keeping numeric kinds self-describing removes schema confusion at extension boundaries. Strict duplicate-key and finite-number checks from RFC 0005 remain required.

Conformance tests

• integer(1) and real(1.0) encode differently, decode to their original variants and have different canonical hashes.
• positive and negative real zero both encode as the same floating-point data item; integer zero remains distinct.
• a map containing "aa" and "z" emits "z" first in CBOR and "aa" first in canonical text.
• encode/decode/encode is a byte fixpoint for both profiles.

Implementation

nuif-codec converts Serde values to ciborium::Value, recursively rejects non-finite values and tags, sorts map entries by their encoded key bytes, and then uses Ciborium’s shortest-width numeric writer. Strict decoding re-encodes the retained value tree and compares bytes before deserializing the NUIF document.

Rejected alternatives

• Restore the type only from a property schema: unavailable to generic tools and unknown extensions.
• Treat integers and integral reals as one logical type: contradicts the declared NUIF value variants and creates surprising adapter behavior.
• Give text and CBOR the same key order: either violates UTF-8 lexical text order or deterministic CBOR encoded-key order.

RFC 0009 — Bound profile-0 ingestion and semantic resources

Document status: accepted (primary evidence and calibration in nuif:research:resource-bounded-serde-and-ciborium). Canonical source.

Motivation

The draft security chapter required bounds but carried unmeasured depth-1,024 and one-million-node examples from unrelated parsers. A byte limit alone does not prevent recursive stack exhaustion, large decoded collections, diagnostic amplification or repeated canonical-key work. Applying a codec limit only after read_to_end also permits the input allocation the limit is intended to prevent.

Decision

Profile-0 decoders and encoders enforce these limits:

Readers consume at most 16 MiB plus the first excess byte and reject that byte without reading the remaining stream. Text nesting is counted outside strings and JSON5 comments before deserialization. CBOR uses an explicit recursion limit. The decoded semantic walk is iterative for property values and runs before recursive validation or evaluation. A canonical writer stops before appending the first byte beyond its profile limit.

Validation retains at most 1,024 ordinary diagnostics and one VALIDATION_DIAGNOSTICS_TRUNCATED issue. It may continue bounded structural work after the retention cap, but it cannot amplify malformed input into an unbounded report.

The reference hostile-input trial is a release build after one fixed warmup. Each enumerated case must produce its expected acceptance/error class within 2 seconds, no more than 64 MiB of allocator traffic and no more than 16 MiB retained at observation time. Those three values are reference-CI regression ceilings rather than cross-implementation format semantics; foreign implementations report their own allocation method while accepting the normative boundary fixtures.

Compatibility

No published profile-0 documents exist. The limits become part of the first executable profile. nuif-text-0 has a lower binary ceiling because its canonical JSON byte arrays expand substantially; the same semantic document remains representable in nuif-cbor-0 up to the 8 MiB model ceiling.

Security

Bounded bytes, syntax and semantic cardinality convert parsing and validation work into finite functions of declared profile limits. They do not replace process-level cancellation, tenant quotas or sandboxing in servers. Future images, fonts, compressed packages, paths and GPU resources require separately measured limits before their profiles can be accepted.

Conformance tests

• exactly-at-limit entity, property, containment, string and CBOR-binary cases are accepted;
• the first byte, syntax level or semantic item over each tested limit returns ResourceLimit naming the exceeded resource;
• strings, escapes and JSON5 comments do not affect the text depth count;
• a wide canonical CBOR map completes within the allocator/time ceiling and malformed document shape remains classified separately;
• CLI and editor readers retain at most the selected limit plus one byte;
• validation output is capped and ends with the truncation diagnostic;
• cargo xtask hostile-inputs writes a machine report with the cases, limits, measurements, toolchain, warmup, allocator method and platform.

Implementation

nuif-core::resource_usage owns semantic accounting. nuif-codec owns encoded, syntax and encoding-specific bounds. The CLI and headless editor bound reads before passing bytes to the codecs. nuif-testing uses an instrumented system allocator in an isolated single-threaded binary, and CI uploads its JSON report.

Rejected alternatives

• Keep depth 1,024 and one million nodes: unsupported by measurements and unsafe for recursive downstream layout.
• Enforce only encoded bytes: shallow compact inputs can still create excessive semantic nodes or diagnostic output.
• Apply the limit after fs::read/read_to_end: too late to bound ingestion allocation.
• Use wall-clock timeout as the sole guard: nondeterministic across machines and incapable of preventing memory amplification.
• Share an 8 MiB binary limit between text and CBOR: canonical text expansion can exceed the encoded limit and allocate a very large generic JSON value tree.

RFC 0010 — Portable resource and package profile

Document status: proposed, with an executable experimental container subset. The. Canonical source.

reference implementation now provides stable assets, deterministic nuif-package-0, explicit verified resolution and the package segment of nuif:experiment:portable-package-resources. This RFC does not add image rendering or general packaged-font conformance to profile 0. The orthogonal nuif-png-rgba8-0 experiment now implements a narrow cross-decoder and CPU image path. The nuif-opentype-static-single-0 experiment likewise implements one narrow package/parser/policy baseline; broader image and font profiles still have to satisfy their acceptance criteria.

Motivation

The current implementation serializes a semantic document as canonical text or CBOR. That is sufficient for profile-0 fixtures because images are unsupported and the one text font is an external pinned conformance input. It is not a portable authoring package: images, fonts, source correspondence and other resources have no common descriptor or delivery contract.

The draft serialization module previously called .nuif a package while leaving its archive technology experimental. The roadmap then described “package/assets” as complete for profile 0. Those statements conflict. This RFC defines a candidate profile and restores the implementation gate.

The design must distinguish:

• stable semantic asset identity;
• identity of immutable resource bytes;
• a locator inside or outside a package;
• source and derivation provenance;
• semantic document hash;
• exact delivered-package hash.

Using one path, URL or hash for all six roles would break editing, offline portability or reproducibility.

Prior art and evidence

• nuif:research:epub-ocf-package-container: OCF separates an abstract container from a constrained ZIP form, requires a manifest and identifies the media type in a fixed first uncompressed member.
• nuif:research:oci-resource-descriptors: OCI binds media type, size and digest, verifying cheap limits and bytes before content interpretation.
• nuif:research:content-addressed-versioning: immutable byte identity is not stable editable entity identity.
• nuif:research:png-image-preservation-and-decoding: original encoded image bytes and declared decode parameters are distinct from decoded caches.
• nuif:research:opentype-font-embedding-and-portability: reproducible text needs exact bytes, but redistribution policy must be explicit.
• nuif:research:penpot: the existing bounded adapter proves defensive ZIP handling but not this package layout or cross-writer determinism.

Proposed semantics

1. Encoding and extension names

• .nuif identifies nuif-package-0, the portable package profile.
• .nuif.cbor identifies bare canonical nuif-cbor-0 document bytes.
• .nuif.json identifies bare canonical nuif-text-0 document bytes.

During the alpha migration, readers MAY recognize historical bare documents whose name ends in .nuif. Writers MUST emit the package for .nuif and MUST use an explicit bare extension for new bare documents. Legacy recognition is read-only compatibility and MUST NOT weaken canonical codec validation.

2. Resource identities

AssetId is the stable semantic identity referenced by document entities. Replacing an asset’s bytes does not change AssetId; it changes the asset’s bound ResourceDigest through a semantic operation.

ResourceDigest in package profile 0 is:

sha256:<64 lowercase hexadecimal digits>

It identifies exact encoded bytes. Implementations MUST verify declared size and digest before decoding the resource.

ResourceDescriptor contains:

digest       ResourceDigest
size         unsigned byte length
media_type   normalized ASCII media type without a retrieval-dependent value
role         source | authoring | derived | cache
locator      embedded path, or explicit linked locator plus expected digest
derivation   required for role=derived; absent for source/authoring/cache

The descriptor is immutable by digest. Metadata that changes interpretation of the bytes belongs in the semantic asset or a versioned decoder profile, not in an untracked package field.

3. Asset semantics

An Asset contains stable identity, kind, current resource digest, portability policy and kind-specific semantic metadata. Initial kinds are image and font; unknown future kinds follow extension-preservation rules.

An image asset records intrinsic dimensions and the decoder profile. An ImagePaint refers to AssetId and records fit, crop, transform, sampling, opacity and declared color conversion. Decoded RGBA and GPU textures are deletable caches, never source resources.

The reference scene interns decoded RGBA by resource digest plus decoder profile and gives commands deterministic numeric surface handles. Its 64 MiB unique decoded-surface total is preflighted from bounded image metadata before inflation. Repeated asset instances therefore do not duplicate decoded pixels or descriptor strings.

A font asset records exact byte digest when available, media type, face or collection index, names used for matching, axes, features, character coverage and policy evidence. Text shaping continues to pin its execution inputs. An optional stable text-to-font AssetId keeps the requested text hash distinct from the effective resource hash: exact bindings require equality, substituted bindings retain the request and select the asset resource, and unavailable bindings select an asset with no resource.

Font portability policy is one of:

• portable: exact bytes can be embedded for the declared package use;
• private_authoring: bytes may exist in a private workspace package but not a distributable portable package;
• linked: bytes are absent; locator and expected digest are explicit;
• substituted: another exact resource is used and fidelity identifies the substitution;
• unavailable: no usable bytes; fidelity identifies the consequence.

OpenType fsType is recorded policy evidence, not a complete legal conclusion.

4. Package members

nuif-package-0 is a ZIP archive with these members:

mimetype
manifest.cbor
document.cbor
blobs/sha256/<64 lowercase hexadecimal digits>

Optional correspondence, capture, report and cache records MAY be added only at paths registered by a later profile. Profile 0 package readers reject unregistered member paths instead of guessing their meaning.

mimetype is the first local-file member, stored without compression, encryption or extra fields. Its exact ASCII bytes are:

application/nuif+zip

This media type is provisional until registration and MUST NOT be represented as IANA-registered.

manifest.cbor and document.cbor are canonical nuif-cbor-0. The manifest declares profile/version, the semantic document descriptor, required capabilities, assets, all resource descriptors and their roles. It does not contain its own digest.

The required-capability set contains at most 256 identifiers of at most 128 ASCII bytes each. Structural readers validate and preserve those requirements. Hosts use capability_report or require_capabilities with an explicitly declared supported set before claiming full package support; missing requirements are reported exactly. Structural decode alone is intentionally available to inert inspection, preservation and extraction tools and is not a semantic-support claim.

A structural SDK, CLI or editor that does not support every required capability MUST keep the package read-only. It MAY validate, hash, extract the bare document and copy the unchanged same-mode package, but it MUST NOT evaluate, change document.cbor or change package mode while carrying capability resources forward unless complete-set negotiation succeeds or a capability-specific authoring profile explicitly detaches those resources. A failed partial negotiation grants no authority. This prevents a content-addressed sidecar from being silently bound to a document revision it never validated.

Every embedded resource is stored at the path derived from its SHA-256 digest. The path is a locator. The manifest digest remains the identity and MUST match the bytes even if a future profile permits another physical layout.

5. Deterministic ZIP profile

The first profile uses stored members only. This deliberately trades archive size for cross-writer byte determinism and simple expansion limits. Images and fonts are usually already compressed; a later measured profile may add a fixed compression method without changing semantic hashes.

Writers MUST:

• emit mimetype first, then every other member in bytewise ASCII path order;
• use only the exact registered ASCII paths above;
• use ZIP method 0 (stored), no encryption, no data descriptors, no ZIP64 unless a later profile permits it, no archive/member comments and no extra fields;
• set the DOS timestamp to 1980-01-01 00:00:00;
• set a fixed creator/version and regular-file external attributes defined by the conformance fixture;
• precompute CRC-32 and sizes so local and central headers agree;
• emit no directory entries;
• emit one central-directory entry for each local member in the same order.

The manual writer and the independently implemented zip 8.6.0 writer now produce identical fixture bytes with creator/version 0x030a, version-needed 10, regular-file attributes 0x81a40000 and the rules above. These values are fixed for the experimental nuif-package-0 implementation. Standards-track stability still requires cross-platform and externally maintained reproduction.

Readers MUST reject duplicate decoded names, backslashes, absolute paths, dot-segments, empty segments, non-ASCII paths, symlinks, directories, split or spanned archives, encryption, unsupported compression, inconsistent headers, undeclared blobs and declared embedded blobs that are absent.

6. External resolution

A portable package embeds every resource required to evaluate its declared profile. A linked/private authoring package may contain a linked locator, but:

• loading a document MUST NOT cause implicit network access;
• a resolver is an explicit caller-supplied capability;
• resolved bytes MUST match declared size and digest;
• redirects and authentication are resolver policy, never package authority;
• credentials, cookies and bearer tokens MUST NOT be stored in locators or provenance records;
• failure to resolve produces a typed fidelity/availability result.

Original URLs are provenance or retrieval hints, not resource identity.

7. Hashes

The semantic document hash remains SHA-256 of canonical document.cbor bytes. It changes only when semantic document content changes.

The package hash is SHA-256 of the complete deterministic ZIP bytes. It proves the exact delivered artifact and changes when package-only records or caches change.

A resource digest is SHA-256 of exact resource bytes. An asset binding is semantic and therefore participates in the semantic document hash. Package locations and deletable caches do not.

Executable narrow image segment and broader proposal

nuif-png-rgba8-0 now executes the smallest unambiguous subset: bounded, non-interlaced RGBA8; no ancillary metadata or one valid pre-image sRGB intent; encoded samples interpreted as sRGB; straight decoded alpha; identity decoder orientation; declared fit/crop, bounded forward affine transform, nearest or fixed-bilinear sampling, opacity and encoded-sRGB integer source-over. It rejects every other colour type, bit-depth, colour signal, Exif/animation chunk and arbitrary metadata. Two independent decoder libraries must agree on exact RGBA bytes. Exact rules and non-claims are versioned in crates/nuif-media/PROFILE.md, and cargo xtask gate-i-image emits its machine evidence.

The separately named nuif-png-basic-rgba8-1 decoder profile adds every non-interlaced PNG colour/depth combination that can normalize to RGBA8 without sample-precision loss. Image-paint transforms use [a c tx; b d ty; 0 0 1] from crop-local source coordinates into the fitted paint rectangle; the CPU reference inverse-samples pixel centers and rejects singular or numerically unbounded matrices. Decoder and paint semantics remain separate contracts even though Gate I exercises them together.

The broader PNG experiment remains separate. It must pin:

• accepted PNG conformance and ancillary chunks;
• decoder library/version or independent semantic rules;
• CICP/ICC/sRGB/gamma/chromaticity precedence and conflict policy;
• Exif orientation behavior;
• straight-alpha decoded representation and explicit premultiplication point;
• output color space, sampling and compositing;
• encoded bytes, dimensions, pixel count, decoded bytes, chunks and metadata limits;
• malformed-image and independent-decoder fixtures.

Animated PNG, JPEG, WebP, AVIF, video and SVG do not enter this profile by fallback. An adapter may freeze a selected animation/video frame as a derived resource and must report the transformation. SVG is imported through a safe declared adapter subset or retained as inert source; scripts and external resources never execute when a package opens.

Executable narrow font segment and broader proposal

nuif-opentype-static-single-0 accepts exact static TrueType-outline sfnt bytes only under a declared portability policy. It requires face index zero, canonically packed and checksummed tables, matching family names and exact Unicode coverage, no variation axes, a matching fsType value, a non-empty license expression and explicit embedding review. Package encode/decode and resolved linked bytes run the same validation. The exact rules and non-claims are in crates/nuif-font/PROFILE.md; cargo xtask gate-i-font compares Skrifa 0.46.2 behind NUIF-owned sfnt validation with a committed HarfBuzz 14.4.0 metadata capture for the pinned Ahem fixture.

This executable slice deliberately rejects TTC, CFF/CFF2, variable, color, bitmap, SVG and WOFF/WOFF2 fonts. The broader font-resource profile must pin:

• parser and table/resource budgets;
• face/collection selection;
• axes, named instances and feature selection;
• coverage and shaping inputs;
• malformed-table fixtures;
• handling of fsType, no-subsetting and bitmap-only flags;
• policy outcomes for portable/private/linked/substituted/unavailable resources.

No profile may infer exact font identity from a family name or screenshot.

Compatibility and migration

Existing canonical document bytes and hashes remain valid. Packaging them does not alter document.cbor or its semantic hash. Current .nuif raw fixtures are readable during alpha through content detection; tools should rewrite them only on explicit save/export and should report the transition.

The package layer belongs above nuif-codec: codecs own canonical bare encodings, while the package implementation owns manifest/resource/ZIP rules. The core owns asset/resource semantics. CLI, editor, WASM, FFI and process adapters call the same package API and MUST NOT carry independent ZIP policy.

The reference nuif-wasm-api-0 binding exposes structural package load, explicit manifest-capability negotiation and deterministic package export over byte arrays. Its cross-surface gate requires both no-op and edited package bytes to match the native SDK exactly and preserves an embedded capability resource without interpreting it. The same gate rejects a semantic edit through a structurally loaded requirement-bearing package before complete-set authorization. This is the browser/plugin package transport; host object access and capability execution remain separate adapters.

Security

The package is untrusted. Before acceptance, the profile requires calibrated limits for total archive bytes, member count, per-member bytes, total expanded bytes, descriptor count, image/font bytes and decoder allocations. Resource size and digest are verified before media parsing. Readers do not extract to a filesystem.

The executable allocation gate additionally requires package-to-session handoff to share immutable resource buffers. Its 8 MiB trial preserves the allocation pointer and permits at most 1 MiB of handoff allocator traffic and retained bookkeeping. A 1,024-instance image trial permits at most 8 MiB of scene-build allocator traffic and 4 MiB retained for one 1 MiB decoded surface. These are reference-CI regression ceilings rather than wire-format limits.

Package resources never execute by being present. Scripts, shaders, links and embedded metadata are inert unless a separately authorized sandboxed capability interprets them.

Conformance tests

nuif:experiment:portable-package-resources must prove:

• two independent writers produce identical bytes on the normative fixture;
• package write/read/write reaches a byte fixpoint;
• required capabilities are bounded identifiers and missing host support is returned as the exact deterministic requirement set;
• document hash is unchanged by package creation and deletable-cache changes;
• asset identity survives byte replacement while the resource/document hashes change as specified;
• missing, extra, duplicate, traversal, symlink, directory, encrypted, unsupported, mismatched-size and mismatched-digest cases fail atomically;
• no implicit external resolution occurs;
• boundary and one-over archive/resource cases pass measured limits.

The narrow PNG experiment and package experiment must pass before claiming nuif-png-rgba8-0. The broader PNG and font experiments must pass before those resource classes are claimed generally.

Rejected alternatives

• Keep .nuif as ambiguous raw JSON/CBOR indefinitely: prevents reliable media identification and resource delivery.
• Use paths or URLs as identity: moving a package or changing a CDN URL would change identity without changing bytes.
• Use content hashes as editable asset IDs: every image replacement would break semantic references and operation history.
• Store decoded RGBA instead of original images: loses source encoding, color metadata and efficient distribution.
• Embed every font found by a browser: local bytes may be inaccessible and redistribution may not be permitted.
• Permit ordinary ZIP/ZIP64/compression options: expands attack surface and prevents a simple first cross-writer byte profile.
• Use TAR: weak random access and no widely deployed first-member media-type convention for this use.
• Use OCI artifacts directly: descriptor ideas are valuable, but registry/image layering semantics are unnecessary for a single design package.

Unresolved questions

• Whether future packages add deterministic compression or rely on outer transport compression.
• Whether correspondence/capture/report records are canonical-adjacent members or separate linked artifacts.
• Media-type registration timing and final name.
• License-expression vocabulary beyond preserved evidence and user/admin policy.

RFC 0011 — Observation, reconstruction and inference provenance

Document status: proposed. This RFC refines RFC 0003 for imported observations and. Canonical source.

probabilistic reconstruction. It does not make any model, capture provider or screenshot profile normative.

Implementation note: nuif-capture, nuif-reconstruct, cargo xtask capture-baselines and cargo xtask reconstruction-provider-manifest exercise a bounded fixed-input subset of these contracts. Every encoded observation bundle carries the canonical manifests behind its provider identities and proposal application rejects an identity that is absent from that registry. cargo xtask gate-j-live separately exercises one pinned local Chromium fixture, structured runtime context, exact response retention, secret canaries and held-out viewport measurement. That automation does not change this RFC’s proposed status or establish a portable capture/reconstruction accuracy profile.

Motivation

NUIF supports deterministic source adapters and is researching browser capture and screenshot reconstruction. These routes expose different evidence:

• a retentive source adapter can preserve exact source bytes and correspondences for its declared subset;
• a browser capture can observe source responses, resources, resolved layout, styles, accessibility and pixels under a pinned execution context;
• a screenshot can observe only visible pixels plus supplied metadata.

Without typed evidence classes, a visually similar generated document could be misreported as a lossless import. This RFC defines the records and fidelity ceilings needed to prevent that category error while keeping models replaceable.

Prior art and evidence

• nuif:research:chromium-source-backed-ui-capture identifies the independent DOM/layout/style/network/font/accessibility/screenshot observations available from a pinned browser protocol.
• nuif:research:live-chromium-cdp-capture compares CDP, Playwright and WebDriver BiDi boundaries and records the bounded transport plus first live executable result.
• nuif:research:design2code-real-world-benchmark records real-page element recall and layout failures in one-shot screenshot-to-code systems.
• nuif:research:reverse-layout-inference and nuif:research:inferui-and-layout-synthesis show why inferred layout needs multiple contexts, alternatives and held-out evaluation.
• nuif:research:confidence-calibration-and-selective-prediction motivates empirical calibration and abstention.
• nuif:research:model-agnostic-screenshot-reconstruction-and-training synthesizes the replaceable-provider, typed-operation and closed-loop plan.

Evidence classes

Every imported or reconstructed property has one or more evidence links whose class is:

• authored_source: exact retained source or host semantic value with stable correspondence;
• resolved_source: value observed from a pinned evaluator/runtime context;
• observed_pixels: value directly measured from identified image pixels;
• inferred: hypothesis produced from observations or heuristics;
• user_confirmed: value explicitly accepted or supplied by a user;
• derived: value produced by a declared deterministic or generative transformation from other evidence;
• unavailable: expected evidence could not be obtained.

user_confirmed does not rewrite the history of an inferred value; both records remain linked. derived names its inputs and transformation identity.

Observation records

An ObservationRecord contains:

observation_id
evidence_class
subject: optional entity/property/resource reference
source_artifact_digest
source_region_or_locator
coordinate_space_and_context
provider: kind + canonical provider-manifest digest
value_or_candidates
raw_confidence: optional
calibrated_confidence: optional
calibration_profile: optional digest
alternatives: ordered candidates with evidence
privacy_and_retention_class

Coordinates MUST name their space: source pixels, device pixels, viewport CSS pixels, crop-local pixels or NUIF logical units. A transformation between spaces is an explicit record.

Raw and calibrated confidence MUST NOT share one field. A calibrated confidence is valid only for the decision type and evaluation distribution identified by its calibration profile.

Capture contexts

A resolved browser observation context records at least browser/protocol build, operating system, viewport, device-pixel ratio, page scale, locale, timezone, color/media preferences, font environment, scroll/pseudo state, navigation identity, readiness/settling policy and animation/time freeze.

Repeated capture under an unspecified context cannot support a reproducibility claim. Multiple contexts are separate records linked by proposed semantic identity.

Cookies, authorization headers, credentials, storage values and secret form content are excluded from export. If exclusion changes an observation, the capture report records the unavailable/redacted evidence without retaining the secret.

Reconstruction interface

Probabilistic systems are optional clients of the normative semantic operation interface. They MUST propose a bounded transaction; they MUST NOT mutate core document structures directly or emit executable code as an implicit operation.

A reconstruction attempt returns:

ReconstructionResult {
  status: valid_result | no_result | budget_exceeded | policy_rejected,
  document_hash: optional,
  accepted_transaction_log,
  observations,
  fidelity_report,
  alternatives_and_abstentions,
  evaluation_report,
  pipeline_artifact_manifest,
}

Every proposed transaction passes syntax/resource limits, operation validation, atomic application and complete document validation. Rejection leaves the prior document unchanged and returns stable diagnostic codes.

Fidelity ceilings

Fidelity describes evidence, not confidence or visual quality.

• authored_source MAY be lossless only inside a declared adapter profile whose correspondence and round-trip laws pass conformance.
• resolved_source MAY be lossless only for the declared resolved observation under its exact context; it cannot prove authored intent.
• observed_pixels and inferred MUST NOT be lossless for authored semantics, source resources, responsive rules, accessibility or behavior.
• screenshot-derived crops, traces or generated resources are derived and at best approximated relative to an unavailable source resource.
• a visually matching flat screenshot cannot satisfy an editable reconstruction profile unless the requested target is explicitly a flat image document.
• behavior inferred from a static screenshot remains inferred even when an icon or label strongly suggests an action.

Confidence MUST NOT promote an item above its evidence-class fidelity ceiling.

Closed-loop correction

A reconstruction profile MAY render and correct a candidate iteratively. Each iteration records input document hash, proposed transaction, validation result, render context/hash, property and visual differences, objective vector, acceptance decision and next document hash.

The loop MUST have finite iteration, model-call, time, memory and resource budgets. It MUST stop on repeated state. Acceptance MUST preserve validity and declared protected metrics. The profile MUST reject objectives that can be satisfied by deleting semantics or covering the viewport with the source screenshot.

No single perceptual metric is a conformance oracle. A reconstruction report uses typed structure/text/geometry/resource/responsive/accessibility measures plus declared visual diagnostics.

Provider and model neutrality

OCR, region detection, UI grounding, proposal engines and correction engines are replaceable providers with capability/artifact manifests. The specification does not name a required model, vendor, training library, parameter count or deployment service.

The implemented nuif-reconstruction-provider-manifest-0 wrapper is canonical CBOR. It binds capabilities, local/remote execution modes and input/output wire profiles to one exact implementation plus optional model weights, processor, adapter, quantization, prompt and tool-configuration artifacts. Released or learned providers require a content-addressed SPDX 3.0.1 or CycloneDX 1.7 inventory; learned providers additionally require a model card. NUIF points to that external inventory instead of defining another SBOM vocabulary. The current browser and screenshot baselines are explicitly development-only, source-bundle-identified providers with no learned-artifact or accuracy claim.

Model weights, processors, low-rank adapters, quantization configurations and training datasets are not NUIF document resources. They are separately versioned operational artifacts. A .nuif package can record which artifact produced an inference without carrying or requiring that artifact for ordinary document use.

Training and distillation boundary

Training is non-normative, but any released reconstruction artifact claiming a NUIF benchmark result has a digest-pinned manifest, model card, dataset datasheets and reproducible evaluation report.

Training examples derived from reconstruction runs include only validated accepted operation transitions as positive targets. Private/authenticated captures are excluded by default and require explicit training consent. Frozen benchmark families are excluded from training and distillation.

LoRA, quantized low-rank adaptation and knowledge distillation are experiment choices. Their use confers no format or conformance status.

Compatibility

Existing provenance/fidelity records remain valid. Implementations may migrate an untyped provenance record to authored_source only when its retained source and adapter profile prove that classification. Otherwise migration uses unavailable or inferred; it does not guess a stronger evidence class.

The current deterministic HTML/SVG/DTCG/Penpot adapter results are unaffected. Their existing profile laws determine losslessness. A future browser capture is a separate adapter rather than a hidden mode of the Tree-sitter HTML adapter.

Security and privacy

Model and provider outputs are untrusted inputs. Parsers enforce operation, observation, string, binary, entity, resource and iteration budgets before application. URLs/scripts in model output are inert. External fetch and code execution require explicit caller capabilities and remain outside reconstruction conformance.

Screenshot text may contain personal, credential or proprietary information. Inference can run locally; remote transfer is an explicit deployment policy. Retention, telemetry and training are separately consented purposes.

Visible prompt injection is data in the screenshot. It cannot alter tool policy, operation grammar, package resolution or security limits.

Conformance tests

The planned baseline, loop and calibration experiments must prove:

• every provider output records artifact identity, source region/context and evidence class;
• invalid, stale or over-budget model operations fail atomically;
• screenshot-only results never emit authored lossless classifications;
• exact source bytes, derived crops and unavailable resources are distinguishable;
• coordinate transforms reproduce observation locations;
• the loop stops on success, no improvement, repeat and budget exhaustion;
• the editable profile rejects flat-image reward gaming;
• raw/calibrated confidence and calibration identity remain distinct;
• automatic/review/abstain decisions reproduce the declared risk threshold;
• secret canaries do not appear in exported observations or training traces.

Rejected alternatives

• End-to-end screenshot-to-document text with no typed observation/operation boundary: invalid outputs and hallucinated semantics become hard to audit.
• Put model calls in nuif-core: makes conformance provider-dependent and the deterministic core non-reproducible.
• Treat one high visual score as lossless: rewards flat screenshots and hides text, structure, resource and responsive failures.
• Store only a whole-document confidence: cannot express one uncertain font, parent or behavior inside an otherwise strong result.
• Require a particular OCR, detector or VLM: confuses an evolving implementation choice with interchange semantics.
• Train before a frozen evaluator exists: no stable evidence that the tuning improves the intended task rather than the training distribution.

Unresolved questions

• Final observation and calibration-profile schemas.
• Whether observations live inside a portable package, a sidecar evidence bundle or both under separate profiles.
• Minimum edit-task suite for an “editable reconstruction” claim.
• Rules for equivalent alternative structures when pixels do not distinguish them.
• Risk/coverage thresholds for automatic application by profile.

RFC 0012 — Behavior as a content-addressed package resource

Document status: proposed, with executable experimental profile. Canonical source.

nuif-behavior-package-resource-0. This RFC chooses the first transport for the bounded behavior experiment. It does not add behavior to the canonical semantic Document, standardize a media type, or authorize execution when a package is opened.

Motivation

The independent Rust/Node behavior traces and the three-engine web lowering show that one finite state-machine subset is executable. Keeping it only as an out-of-band JSON fixture, however, cannot test offline delivery, package identity, corruption handling or document-reference validation after a package round trip. Moving it directly into the canonical document would make a much larger and less-tested compatibility commitment.

The narrow requirement is therefore: transport one exact behavior program with one exact document using the current deterministic package, while keeping behavior modular and inert until an explicit capability-aware runtime accepts it.

Prior art and evidence

• nuif:research:behavior-portability-state-machines defines the finite trace contract and its current exclusions.
• nuif:research:behavior-package-resource-binding compares OCI descriptors, EPUB container processing and KHR_interactivity, then records the executable package decision.
• RFC 0010 already defines deterministic package manifests, digest-addressed blobs, resource roles, explicit resolution and the rule that resources do not execute merely because they are present.

Profile

nuif-behavior-package-resource-0 uses nuif-package-0 unchanged. A conforming attachment has all of these properties:

• exactly one resource descriptor has media type application/nuif-behavior+cbor;
• that media type is provisional and is not an IANA-registration claim;
• the descriptor role is source, its locator is embedded, and it has no derivation record;
• the embedded path is the normal blobs/sha256/<digest> path;
• the resource bytes are canonical nuif-cbor-0 encoding of exactly one nuif-behavior-state-machine-0 BehaviorProgram;
• required_capabilities contains nuif-behavior-state-machine-0;
• the complete program validates against document.cbor before attachment and after package decode.

Zero behavior resources with no behavior capability is a valid package without behavior. A capability with no resource, a resource without its capability, more than one behavior resource, a linked behavior resource, non-canonical bytes or invalid document references fail the attachment profile.

Identity and binding

The behavior resource digest identifies its exact canonical program bytes. The document canonical hash identifies exact semantic document bytes. Neither is redefined to include the other.

manifest.cbor carries both descriptors, and the deterministic complete package hash binds their delivered pairing. Consequently:

• attaching behavior changes the package hash but not the document hash;
• changing the document changes both its hash and the complete package hash;
• the same behavior resource can be deduplicated by digest without claiming it is valid for every document;
• every explicit load revalidates stable entity references against the actual package document.

Processing and authority

Package processing is layered:

1. NuifPackage::decode validates the deterministic ZIP, canonical manifest, document, descriptors, sizes, hashes and embedded bytes.
2. capability_report or require_capabilities compares every package requirement with a caller-declared host capability set without executing it.
3. attached_behavior opts into this RFC, checks descriptor/capability agreement, decodes canonical behavior bytes and validates the program against the document.
4. A caller creates a behavior runtime only with an explicit set of available abstract-effect capabilities.
5. A host adapter separately maps admitted effects under its own profile and security policy.

Step 1 never implies steps 2–5. Generic tools may inspect, copy and deterministically re-encode the package without executing the resource. Tools that claim full behavioral conformance must understand the required behavior capability; a structural package decode alone is not such a claim.

Security and limits

The package verifies declared byte length and SHA-256 before canonical CBOR or behavior validation. Existing package byte/resource/member limits and behavior state/transition/action/string limits both apply. Linked behavior is rejected so the profile neither invokes a resolver nor grants network authority.

The program remains data. It contains no scripts, dynamic imports, filesystem paths, URLs, timers or host calls. Runtime creation and every host lowering are separate authorization decisions.

Conformance

nuif:experiment:behavior-package-resource requires:

• canonical program bytes and exact attach/decode/encode fixpoint;
• unchanged document hash and changed package hash after attachment;
• exact required capability, source role, media type and digest-derived path;
• refusal of missing/duplicate/linked/malformed/rebound resources;
• rejection of package-byte corruption before behavior decoding;
• an independent standard-library ZIP reader checking exact package bytes, member order/metadata, CRC and the content-addressed behavior resource.

cargo xtask gate-behavior includes this gate before the independent behavior trace gate. CI archives all generated package and report artifacts.

Rejected alternatives

• Canonical Document.behavior in the first experiment: premature semantic commitment and forced support in all readers.
• A special behavior.cbor ZIP path: duplicates the resource manifest and requires a new container path profile.
• An opaque extension inside an arbitrary entity: gives behavior no unique package-level discovery or cardinality rule and couples it to one visual node.
• JSON attachment: creates a competing canonical encoding and larger parsing surface.
• Automatic execution on package open: violates RFC 0010’s inert-resource boundary and prevents safe inspection tools.

Unresolved questions

• Which next event/effect types remain finite and portable across web, native and presentation hosts.
• When independently implemented adapters provide enough evidence to propose a canonical behavior model.
• Final media-type naming and registration timing.

ADR 0001: Rust for the reference core

Document status: accepted. Canonical source.

Decision

The initial reference implementation uses Rust for the canonical in-memory model, operations protocol, validation, codecs, layout/renderer integration, headless tooling, and WASM boundary.

Rationale

The project needs memory safety for hostile document parsing, deterministic systems-oriented behavior, strong enum/type modeling, high-performance geometry/text/GPU ecosystems, native and WebAssembly targets, fuzz/property testing, and stable FFI boundaries. Rust gives the strongest combined fit among the evaluated mainstream implementation languages.

The editor UI and source-specific adapters may use TypeScript or target-native languages where that produces a cleaner integration. Those layers must communicate through stable protocol/API boundaries and must not redefine the canonical model.

ADR 0002 — Use Taffy as initial CSS-family layout evaluator

Document status: accepted for prototype. Canonical source.

Taffy provides Rust implementations of Block, Flexbox and Grid and is already embedded by multiple UI systems. NUIF will wrap it behind its own evaluator interface. Taffy types MUST NOT become canonical schema types.

Constraint/freeform/proposal-response semantics remain separate evaluators/lowerings.

Gate C verification

The first executable use is an independent test lowering, not canonical-schema coupling: nuif-testing pins Taffy 0.14.0 and compares it with Chrome for Testing 152.0.7977.64 and the profile-0 reference evaluator. This exposed and corrected definite cross sizes being overwritten by stretch. The v0 and generated stack/flex subset now agree within measured fixture-local bounds.

Grid remains intentionally unwired in the reference evaluator because the current authored model has no track-sizing or item-placement fields. The differential report classifies those differences as schema loss. A follow-up schema decision is required before a Taffy Grid lowering can be called representable.

ADR 0003 — Renderer abstraction with Vello/wgpu experiment

Document status: accepted for prototype. Canonical source.

Use a NUIF-owned render-scene boundary. Implement an interactive Vello/wgpu backend experiment and retain the ability to add CPU/reference backends for deterministic conformance.

No Vello internal data type is normative NUIF state.

ADR 0004 — Encoding strategy

Document status: provisional. Canonical source.

Define serialization independently of the logical model. Prototype a canonical text form and deterministic CBOR binary form. Benchmark schema-based alternatives before ratification.

Opaque extensions are explicit NUIF values/bytes so preservation does not depend on a codec’s unknown-field implementation.

Current experimental outcome

nuif-text-0 and nuif-cbor-0 are executable profile-0 encodings. The codec decision gate measures both only after semantic, canonical and opaque-data fixpoints pass. Deterministic CBOR materially reduces file size, but its current typed decoder is not faster than canonical text, so performance alone does not ratify it as the only future binary profile.

Schema codecs must present a complete NUIF mapping before benchmark admission. Protobuf is presently excluded because its own specification says deterministic binary serialization is not canonical. FlatBuffers offers direct access but permits multiple byte layouts for equal values and does not prove retention through an old-schema edit. Cap’n Proto is the next candidate because it specifies schema-agnostic canonicalization and traversal limits; it remains unadmitted until cross-version retentive editing and two canonical writers pass.

The decision report is generated by cargo xtask codec-benchmark; transient host timings are evidence artifacts, not normative limits.

ADR 0005 — Keep CRDT state out of canonical documents

Document status: accepted. Canonical source.

Collaboration engines operate over NUIF semantic operations and materialize canonical snapshots. Replica clocks/tombstones/history belong to a collaboration profile or sidecar, not every .nuif document.

This permits Automerge/Yjs experiments and independent non-collaborative implementations.

ADR 0006: Rust-native reference editor on Masonry, Vello and AccessKit; toolchain policy

Document status: accepted. Canonical source.

Decision delegated to research on 2026-08-29. Evidence: nuif:research:masonry-editor-stack-decision, nuif:research:rust-toolchain-and-msrv-policy, nuif:research:masonry-xilem-and-linebender-test-harness, nuif:research:egui-and-egui-kittest, nuif:research:iced-slint-gpui-makepad-floem, nuif:research:accesskit-semantic-ui-testing, nuif:research:vello-testing-and-cpu-reference, nuif:research:wasm-headless-execution.

Context

docs/whitepaper/06-language-and-runtime-choice.md and apps/editor/ARCHITECTURE.md proposed a Svelte 5 and TypeScript shell over a Rust/WASM core. The editor’s role (apps/editor/README.md, RFC 0004) is a test instrument: headless execution, deterministic snapshots through a CPU reference path, an accessibility tree that carries entity identifiers, and the same harness as the CLI.

Decision

Stack

1. The reference editor is a Rust binary crate (apps/editor) built directly on Masonry (retained widget tree) with Vello rendering and AccessKit. Xilem is not used: its view layer lags the widget set (xilem issue 1710) and entity-to-widget identity must be explicit in the editor.
2. Masonry is pinned by full SHA to the reviewed refpath/xilem fork at 1b96eb8; its parent eabfe0a carries the wgpu 29 migration, and it descends from the evaluated upstream main revision b81d8d7 (2026-08-28). The 0.4.0 release of 2025-10-29 lacks the Canvas widget, paints into a Vello 0.6 Scene, and screenshots only through wgpu. The pinned line provides Widget::paint over an imaging::Painter, Canvas::update_scene recording an imaging::record::Scene, and masonry_testing rasterization through imaging_vello_cpu without a GPU.
3. The editor canvas is a lowering from NUIF RenderScene to imaging commands. NUIF’s own CPU reference renderer remains the conformance oracle; Masonry’s vello_cpu path rasterizes shell chrome for headless screenshot tests only.
4. For every type that crosses the widget boundary (Vello, Parley, AccessKit, wgpu), the editor crate follows Masonry’s pinned versions. A cargo metadata probe of Masonry main with independently chosen Vello 0.10, Parley 0.11 and AccessKit 0.25 produced duplicate Vello (0.8/0.10), wgpu (28/29), Parley (0.8/0.11.1), AccessKit (0.24.1/0.25) and four accesskit_consumer versions; the editor build therefore disables NUIF’s standalone Vello backend and exchanges pixel buffers with the reference path as bytes.
5. The Svelte shell becomes a later browser demonstration of the WASM bindings. Engine parity in browsers is tested through wasm-bindgen-test and Playwright layout oracles; in-browser WebGPU pixel oracles are not used.

Toolchain and MSRV

6. rust-toolchain.toml pins the current stable, 1.98.0 (released 2026-08-20). The pin is raised in one dedicated commit within each release cycle.
7. rust-version is 1.96: max(toolchain − 2, highest dependency MSRV), where Masonry main requires 1.96, imaging 1.92, Vello and Parley 1.88, wgpu 1.87, AccessKit, HarfRust and proptest 1.85. This coincides with Masonry’s own N-0..N-2 practice and with Bevy (1.96), Zed and Servo (1.97.1) and rust-analyzer (1.98).
8. The workspace uses resolver = "3" so that dependency resolution is MSRV-aware.
9. CI runs the main job on the pinned toolchain and an msrv job that checks the workspace on 1.96.0.

Licensing

10. Masonry is licensed Apache-2.0 only; Vello, Parley and imaging are Apache-2.0 OR MIT; AccessKit is MIT OR Apache-2.0; accesskit_winit, winit, tree_arena, insta and ciborium are Apache-2.0 only. Depending on Apache-2.0-only crates does not constrain NUIF’s Apache-2.0 OR MIT (Apache-2.0 §4 obliges notice retention on redistribution and permits different terms for one’s own work); the only downstream effect is on GPLv2-only consumers.
11. deny.toml allows exactly: MIT, Apache-2.0, Apache-2.0 WITH LLVM-exception, BSD-2-Clause, BSD-2-Clause-Patent, BSD-3-Clause, ISC, Zlib, Unicode-3.0, BSL-1.0, CC0-1.0, 0BSD, Unlicense. BlueOak-1.0.0 is not allowed; minicbor is therefore excluded (RFC 0005 selects dcbor, BSD-2-Clause-Patent).

Rationale

• Masonry main is the only candidate whose harness returns the frame’s visual layer plan and AccessKit TreeUpdate from one redraw(), accepts ActionRequests directly, controls time, hosts a custom-painted canvas, and rasterizes without a GPU.
• egui: egui-wgpu callbacks paint inside egui’s own render pass, while Vello requires compute passes; egui would duplicate the text and vector stack; egui_kittest’s query API remains the model for NUIF’s harness surface.
• Floem: no AccessKit (issues 8 and 973 open). Blitz: custom paint sources exist but the harness is unpublished. GPUI: builds an AccessKit tree per frame but exposes no query in test contexts and requires latest stable. iced: no accessibility tree. Slint: licence and DSL-owned element tree.

Widget inventory

Masonry main ships 37 widgets including Split (draggable), CollapsePanel, Selector, StepInput, TextInput, VirtualScroll, Canvas and a tooltip layer. Missing for apps/editor/UI-SPEC.md and composed in the app crate: tree view (layers panel), drag-and-drop reparenting (emits protocol Move from canvas pointer events), menus and tab strip, colour picker, keyboard-shortcut table, multi-line text input (newlines unsupported in TextInput), text undo/redo (xilem issue 1417).

Risks and mitigations

• API churn: paint signature, layout system and renderer changed between 0.4.0 and main without a changelog; 304 days without a release. Mitigation: git pin, single bump commits, harness behind NUIF’s session-driver trait, no Masonry types in crates/.
• Split pointer defect (xilem issue 1581); unsafe NodeId workaround in access_node (AccessKit issue 701, fixed in accesskit_consumer 0.36 while Masonry pins 0.35). Mitigation: isolated in the app crate; unsafe_code = "forbid" stays in crates/.
• vello_cpu regressions affect shell screenshots only (tier 2 tolerance); the render suite uses NUIF’s CPU reference.

Consequences

• rust-toolchain.toml, Cargo.toml (rust-version, resolver), .github/workflows/ci.yml and deny.toml are updated with this ADR.
• apps/editor/ARCHITECTURE.md, apps/editor/UI-SPEC.md and docs/whitepaper/06-language-and-runtime-choice.md reference this ADR.
• The editor exposes entity identifiers through AccessKit author_id; the harness queries by role, label and identifier and dispatches actions without pointer synthesis.

Unverified

Linebender Zulip release announcements were not retrieved; the anyrender CustomPaintSource trait was not located; the 1.99 release date (2026-10-01) is computed from the cadence, not announced.

ADR 0007: Tag-driven native editor prereleases

Document status: accepted. Canonical source.

Decision delegated to research on 2026-08-30. Evidence: nuif:research:github-release-delivery-and-provenance and nuif:research:cargo-workspace-xtask-and-ci-layout.

Context

The native editor packaging task produces host-specific archives and verifies their executable entry points. CI retained those archives as temporary workflow artifacts. It did not provide a version contract, a durable download location, cross-platform checksums, or build provenance. Application delivery requires a tag-to-version invariant and a publication transaction that does not expose a partially assembled release.

Decision

1. The editor uses Semantic Versioning independently from unpublished library crates. The first application version is 0.1.0-alpha.1 and its release tag is v0.1.0-alpha.1.
2. A release tag identifies one immutable source revision. Tags are not moved; a correction increments the prerelease number.
3. .github/workflows/release.yml validates that the tag equals v followed by the editor package version and that the checkout is clean.
4. The release workflow runs the complete repository harness before building native packages on Linux x86-64, Linux Arm64, Windows x86-64, macOS Arm64, and macOS x86-64 hosts.
5. Each archive name contains the editor version, operating system, and architecture. Each package manifest records its source revision, version, platform, architecture, executable and archive SHA-256 digests, smoke tests, and signing status.
6. GitHub artifact attestations cover every archive and platform manifest. The publication job creates and attests SHA256SUMS, a CycloneDX software bill of materials, and release-manifest.json.
7. Publication creates a draft, attaches every asset, and then publishes the prerelease. A failed build or upload leaves no published partial release.
8. Alpha packages are unsigned. macOS Developer ID signing and notarization, Windows publisher signing, installer publication, and automatic updates are credentialed stages that require separate review.
9. cargo-dist is not introduced for the alpha because the existing xtask owns native application layouts, manifests, trials, and smoke tests.

Consequences

• GitHub Releases becomes the durable download surface for tagged editor builds. CI artifacts remain diagnostic evidence for ordinary commits.
• ADR 0009 makes locally built, user-scoped source installation the primary developer path. Release archives remain durable evidence and an expert opt-in path rather than the default installation mechanism.
• Application consumers can verify SHA-256 checksums and GitHub provenance without building the repository.
• Unsigned alpha packages may trigger Gatekeeper or SmartScreen warnings. The release notes state this limitation.
• The stable-release gate remains open until macOS and Windows signing identities, credential rotation, and update policy are approved.

ADR 0008: Vendor products integrate through host adapters

Document status: accepted. Canonical source.

Decision delegated to research on 2026-08-30. Evidence: nuif:research:figma-plugin-and-rest-api-as-automation-surface, nuif:research:figma, and nuif:research:adobe-uxp-host-integration.

ADR 0012 amends clauses 5 and 8 for the active vendor priority: Affinity is the desktop interchange target and Canva is the programmable adoption target. The Adobe clauses below remain the historical decision and prior-art record.

Context

The native NUIF editor is a reference implementation and conformance tool. It is not a plug-in runtime for every design product. Figma and Adobe applications already own their document stores, undo systems, permissions, extension runtimes and distribution channels. Embedding the NUIF editor executable would duplicate the host shell and would not provide access to the host document.

Source adapters use byte spans because they synchronize retained source. Host APIs expose objects and properties instead of source bytes, so they require a different correspondence record and evidence report.

Decision

1. A vendor product integrates NUIF through a host adapter that maps its public object API to canonical NUIF documents and operations. It does not embed the NUIF editor application.
2. nuif-adapter::HostAdapterReport is the common evidence envelope for API hosts. It records profile, direction, host/API versions, optional host revision, canonical hash, host-object correspondence, fidelity and unmapped-data preservation.
3. Every host and product has a separately versioned bounded profile. “Figma” and “Adobe” are not fidelity claims by themselves.
4. Figma uses a user-run TypeScript/JavaScript Plugin API bridge with dynamic page loading. The default package has no network access. UI-frame file transfer and host-object mutation are separate message channels.
5. Adobe UXP delivery is one .ccx package per supported host. The initial profile targets InDesign. Photoshop is separate and performs all mutations inside one executeAsModal transaction. Illustrator remains unclaimed until its current public SDK and package contract are researched and tested.
6. Host correspondence uses host object identifiers plus namespaced NUIF metadata when the host documents such persistence. Duplicate or missing persisted identifiers are repaired with new NUIF identifiers and reported; silent identity reuse is forbidden.
7. Vendor plug-in versions are independent of the native editor version. A plug-in declares the NUIF profile/spec revisions it supports and runs the same checked-in fixtures before publication.
8. GitHub Actions may build and retain review artifacts. Publication into Figma Community or Adobe Marketplace remains a separately authenticated, host-governed release step.

Consequences

• Vendors can adopt NUIF without adopting the reference editor UI or Rust.
• API and source adapters share fidelity semantics while using correspondence appropriate to their medium.
• A credential-free repository can test pure mapping logic and checked-in host snapshots, but live-host claims require the named host/version evidence.
• Marketplace identifiers, approvals and publisher accounts remain outside the repository and cannot be inferred from a GitHub release.

ADR 0009: Source-built developer installation

Document status: accepted. Canonical source.

Decision delegated to research on 2026-08-30. Evidence: nuif:research:developer-source-installation-and-os-trust and nuif:research:github-release-delivery-and-provenance.

Context

NUIF Editor will remain a developer-facing reference and conformance tool. Unsigned native archives are useful build evidence, but making them the normal installation path couples routine research use to Apple and Microsoft publisher-reputation systems. Marketplace publication and paid signing identities are not architectural requirements for a developer tool.

A different path must still preserve source identity, dependency locking, platform integration, updates, rollback and safe removal. It must not claim that local compilation bypasses every managed-device policy or weaken an operating system’s security controls.

Decision

1. The primary editor installation is a local build from a clean, pinned source revision using the checked-in Cargo.lock and repository Rust toolchain.
2. cargo xtask owns user-scoped install, update, doctor, rollback and uninstall commands. There is no system-wide installation mode.
3. Source installs record the version, source revision and cleanliness, lockfile digest, toolchain, platform, architecture and installed binary digest in a machine-readable receipt.
4. The alpha channel resolves only published prereleases. Its release manifest must pass GitHub attestation verification for the NUIF release workflow, tag and source revision before the revision is built.
5. Updates are explicit. The active and previous immutable installations are retained so activation can be rolled back without rebuilding.
6. macOS installs a locally built, ad-hoc-signed application under the user’s Applications directory. Windows installs under the user’s local application directories and may create a user Start-menu shortcut. Linux installs under user XDG and ~/.local paths.
7. The lifecycle never disables Gatekeeper, System Integrity Protection, Defender, SmartScreen or Smart App Control and never adds a certificate to a trust store. Managed-device exceptions require organization approval.
8. GitHub release archives remain CI evidence, reproducibility material and an expert opt-in path. They are not described as trusted publisher-signed applications.
9. Homebrew source formulae and Nix flakes are compatible future convenience layers. A Scoop bucket downloads the unsigned Windows archive and therefore cannot replace the source-built trust path.

Consequences

• A developer can install and update the editor without Apple Developer Program membership, Microsoft Store publication or administrator access on an ordinary development machine.
• The default path takes compilation time and requires the platform Rust/native build prerequisites.
• A locked-down machine may still reject locally built unsigned code. Its administrator must supply an approved certificate or policy; NUIF does not work around that control.
• Release automation and source installation have separate responsibilities: releases attest the channel input, while the local lifecycle owns the executable installed on the developer’s machine.

ADR 0010: Bounded retentive Svelte source adapter

Document status: accepted. Canonical source.

Decision delegated to research on 2026-08-30. Evidence: nuif:research:svelte-source-adapter-surface, nuif:research:tree-sitter, and nuif:research:dependency-and-subsystem-audit.

Context

Svelte source combines declarative markup with JavaScript, TypeScript, preprocessing, directives, blocks and component-scoped CSS. NUIF needs useful source interchange without claiming that static parsing reproduces an application runtime or rewriting unrelated developer source.

Decision

1. nuif-svelte implements only the versioned nuif-svelte-static-0 profile. It maps regular div containers and span literal text through explicit data-nuif-* markers and a fixed inline-style vocabulary.
2. tree-sitter-svelte-next 0.1.1 supplies the production concrete syntax tree and UTF-8 byte ranges. It does not define Svelte semantics.
3. Exact official svelte 5.57.0 is the foreign parser/compiler oracle. It is test tooling only and never enters a NUIF deliverable.
4. Synchronization edits only recorded scalar spans, rejects stale or structural changes atomically, reparses the result, and requires canonical NUIF equality.
5. Scripts, stylesheets, preprocessors, expressions, blocks, directives, components, special elements and dynamic attributes are outside profile zero. Top-level comments and whitespace may be retained but have no claimed semantic mapping. Other top-level nodes are rejected.
6. Component CSS is deferred. A later profile must define selector ownership, cascade, specificity, Svelte scope hashing and source-locality rules before it can be accepted.

Rationale

The official compiler is the only suitable semantic authority, but its printer may normalize whitespace and quoting. A concrete syntax tree is therefore the right production mechanism for retained spans, while live official compilation prevents that community grammar from becoming a self-oracle. The broader unofficial Rust compiler adds a second semantic implementation and a much larger dependency graph without improving the deliberately static boundary.

Consequences

The adapter is useful for generated components and controlled developer tools, not arbitrary Svelte applications. Its conformance claim includes exact round-trip and byte-complement preservation plus pinned official parse/compile acceptance. Runtime rendering equivalence and general CSS equivalence remain unclaimed.

ADR 0011: One byte-oriented SDK precedes foreign ABI stabilization

Document status: accepted. Canonical source.

Decision delegated to research on 2026-08-31. Evidence: nuif:research:rust-sdk-and-foreign-language-bindings and nuif:research:wasm-headless-execution.

Context

The reference engine already has a headless nuif-api session and working CLI, WASM, MCP and editor clients. The WASM crate nevertheless duplicated bare document decoding, validation, canonical export, hashing and session history composition. Adding C, Swift and Kotlin wrappers before removing that duplication would create more places for semantics to escape the core.

Rust does not promise stability for its native ABI. A public C ABI can be stable only after the project specifies ownership, buffers, errors, panics, threads and symbol compatibility. Swift and Kotlin additionally need generated language wrappers and platform packaging; binding generation alone is not a distribution system.

Decision

1. nuif-api::NuifDocument is the single package-aware, byte-oriented Rust SDK façade. It owns no filesystem, network, plug-in or process authority.
2. The façade accepts explicit canonical text/CBOR profiles, separately loads fully verified packages, applies typed semantic operations and exports bare encodings or deterministic packages through existing implementations.
3. WASM, MCP, CLI and editor wrappers may add transport limits and host policy, but must not implement document semantics independently.
4. Cross-surface conformance requires exact canonical bytes, hash, diagnostics and patch behavior for the shared subset.
5. No stable C ABI is declared while the semantic SDK is 0.0.x. The eventual nuif-ffi is a small separately reviewed crate over SDK byte records, not a C representation of internal Rust structs.
6. C/C++ headers should be generated with pinned cbindgen. Swift/Kotlin wrappers should prefer pinned UniFFI over handwritten per-language ownership glue, but only after ABI, sanitizer and native-consumer gates are defined.
7. Each foreign binding and platform package has an independent profile, version, compatibility report and release stream.

Consequences

• Direct Rust and browser clients use one operation and serialization path.
• Packages and embedded resources survive SDK edits without giving wrappers implicit resolution authority.
• The repository avoids advertising a stable ABI whose memory or error contract has not been reviewed.
• Native mobile bindings remain planned, with explicit promotion evidence instead of placeholder exports that appear production-ready.

ADR 0012: Prioritize Affinity interchange and Canva host adoption

Document status: accepted. Canonical source.

Decision delegated to research on 2026-08-31. Evidence: nuif:research:affinity-interchange-and-adoption, nuif:research:canva-apps-and-connect-adoption, nuif:research:svg and nuif:research:figma-plugin-and-rest-api-as-automation-surface.

This ADR amends the active vendor priorities in ADR 0008. It does not erase the historical Adobe UXP research or change ADR 0008’s common host-report contract.

Context

The initial vendor plan selected Figma plus host-specific Adobe UXP packages. The project needs an accessible desktop product for human interchange trials and a supported programmable product with a realistic public distribution path. The all-new Affinity is available at no cost and spans vector, photo and layout work, but the reviewed official surface does not expose a stable public document API or native file schema. Canva exposes both an in-editor Apps SDK and off-platform Connect APIs, with explicit capability and review constraints.

Treating these products as equivalent would either overclaim Affinity automation or reduce Canva to lossy file conversion. They require different profiles and evidence.

Decision

1. Affinity replaces Adobe as the active desktop vendor-adoption priority. Its first profile is a user-mediated SVG interchange trial over the already executable nuif-svg-0 subset, not a native plug-in or .af* parser.
2. Native Affinity files remain opaque provenance. NUIF will not reverse- engineer them or use pointer/keyboard UI automation as conformance evidence. A future public scripting/document API requires a new profile.
3. Canva is the primary programmable vendor-adoption path. Its first profile uses stable Apps SDK Design Editing APIs on one fixed-dimension current page and only the documented supported element subset.
4. A Canva import validates a complete bounded plan and applies it with one confirmed sync. Locked, unsupported, conflicting or expired sessions fail before mutation and every loss is represented in HostAdapterReport.
5. nuif-wasm may be bundled in the Canva iframe under the documented CSP, but only the Apps SDK owns host objects and mutation. Remote executable code, workers and preview APIs are absent from the public profile.
6. Canva Connect APIs are a secondary OAuth workflow. Because their current format lists omit NUIF, SVG/PDF use is explicitly lossy and no native NUIF Connect round trip is claimed.
7. The Affinity kit and Canva app each have independent profile and package versions. CI may build evidence and review artifacts. Marketplace submission, developer verification, approval and release remain explicit authenticated human/organization operations.
8. Adobe UXP research remains available as historical prior art and a possible contributor-maintained future adapter, but it is removed from the active target inventory and roadmap queue.

Consequences

• Contributors can run the desktop interchange experiment without purchasing a separate design application.
• The project distinguishes evidence from a file-interchange host and an API host instead of implying that one adapter architecture fits both.
• Affinity coverage initially inherits the narrow SVG exclusions and cannot claim native identity, undo or round-trip fidelity.
• Canva offers a realistic source-bundle and marketplace adoption route, but API stability, review, identity disclosure, OAuth and live-host evidence are external gates.
• Historical research remains auditable without steering implementation toward a vendor path that is no longer prioritized.

Conformance

The profile-0 baseline is executable through the nuif-conformance package and xtask gates. It covers structural validation, canonicalization, parser/serializer round trips, unknown-extension preservation, operations/replay/inversion, responsive stack/flex layout, bounded explicit fixed/fr Grid tracks and placement, pinned shaping and hard-line text, deterministic solid rectangle/ellipse and bounded RGBA8 image CPU rendering, measured codec/model/resource limits, pinned browser/Taffy differential layout, editor-driver parity, seven bounded retentive adapter profiles, one pure Figma snapshot/mutation-plan mapping profile and machine reports. Broader CSS Grid, paths/instances, broader image and paint profiles, live vendor adapters and perceptual tiers remain outside the implemented profile.

Install the locked Chrome for Testing build once with cargo xtask browser-install, then run cargo xtask gate-c. The report at target/layout-differential-report.json contains the raw NUIF, Taffy and browser boxes, engine versions, source revision, fixture-local calibration and every classified divergence. A schema-loss classification may describe input outside a declared profile, but cannot excuse a mismatch inside the bounded Grid profile; unclassified or evaluator differences fail the command.

Run cargo xtask gate-d for both text and paint. It writes target/text-pinning-report.json and target/render-profile-report.json; committed hashes, missing font failures, color validation and property-attributed unsupported/preserved fidelity are blocking checks.

Automated and conventional QA run the same headless tests. GUI automation is supplementary; semantic API operations are the primary test interface. HARNESS.md specifies the workspace layout, fixture format, determinism controls, oracles, trial loop, reducer and report schema.

Run cargo xtask editor-hostile-inputs for the release-mode semantic editor boundary. It rejects excessive snapshot allocations before rendering, checks finite parsing across every accessibility numeric family, and proves failed transactions and history boundaries preserve the document and replay log.

Run cargo xtask performance for the portable release-mode smoke profile. It measures validation, both codecs, protocol apply, layout, scene lowering, CPU rasterization, end-to-end snapshots, bounded PNG and font inspection, and real embedded-resource package paths; records median/p95 latency and warmed allocation counts; enforces deliberately broad catastrophic-regression budgets; writes target/performance-profile-report.json; and compiles the statistical suite. Run cargo bench -p nuif-conformance --bench profile_zero -- --noplot and cargo bench -p nuif-conformance --bench system_surfaces -- --noplot on controlled hardware for scaling and subsystem comparisons. Shared CI timing is evidence, not a fine-grained cross-machine baseline. See PERFORMANCE.md for the workload contract, comparison workflow and interpretation rules.

Run cargo xtask gate-svg for the bounded nuif-svg-0 adapter. It checks exact model round trips, seven byte-local semantic edits, preservation of the complete unchanged-byte complement, typed hostile cases and a public-CLI export/sync/import bridge. The machine report and synchronized sources are written under target/svg-sync-*; the declared subset and its exclusions are specified in adapters/svg/PROFILE.md.

Run cargo xtask gate-dtcg for the bounded nuif-dtcg-scalar-0 adapter. It checks exact scalar-token round trips, integer/real discrimination, eight byte-local edits, root and token extension preservation, duplicate/depth/count and source limits, and a public-CLI bridge. Reports and retained sources are written under target/dtcg-sync-*; groups, aliases and composite types remain outside the declared profile.

Run cargo xtask gate-penpot for the bounded nuif-penpot-v3-0 package adapter. It imports a fixture from the official JavaScript library, proves deterministic export and exact no-op archive retention, applies eight mapped JSON edits while preserving opaque members, exercises hostile ZIP boundaries and completes an export/sync/import bridge through the public CLI. Reports and packages are written under target/penpot-sync-*; components, libraries, interactions, media, paths, layout and compact pages remain outside the profile.

Run cargo xtask gate-react for the bounded nuif-react-jsx-0 source profile. It extracts one directly returned marked intrinsic subtree without executing JavaScript, applies 11 byte-local scalar edits, preserves unrelated module source, rejects eleven dynamic/hostile cases and exercises the public CLI bridge. Reports and synchronized JSX are written under target/react-sync-*; components, hooks, spreads, handlers, runtime expressions, TSX and browser runtime equivalence remain outside the profile.

Run cargo xtask gate-svelte for the bounded nuif-svelte-static-0 source profile. It applies 11 byte-local edits, preserves the complete unchanged-byte complement, rejects 13 executable or hostile inputs, completes the public CLI bridge, and then parses and compiles both synchronized outputs with exact official svelte/compiler 5.57.0. Reports and components are written under target/svelte-*; scripts, blocks, directives, components, component CSS and runtime rendering equivalence remain outside the profile.

Run cargo xtask gate-figma for the credential-free nuif-figma-plugin-snapshot-0 mapping. It repeats normalized snapshot bytes, round-trips the declared subset through the CLI, repairs portable identity and exercises unsupported-property and hostile-input paths. It does not run inside Figma or certify host mutation behavior.

Run cargo xtask gate-wasm for nuif-wasm-api-0. It compiles the same core for wasm32-unknown-unknown, generates Node and direct-browser JavaScript plus TypeScript surfaces, initializes the web target in pinned headless Chrome, exercises load/validate/hash/text/CBOR/patch/undo/redo in Node and requires the edited canonical bytes to equal the native CLI output. The report and direct-browser developer package are written to target/wasm-conformance-report.json and target/nuif-wasm-web. This gate does not claim browser-layout, host plug-in or WASI CLI conformance.

Run cargo xtask adapter-audit to validate the complete advertised adapter inventory independently of executable profile tests. It requires research and explicit boundaries for twelve targets, checks crate/profile/gate references for the ten integrated profiles and prevents researched or externally blocked targets from claiming executable directions.

Run cargo xtask diagnostic-audit to require every model, layout and trial diagnostic code to appear exactly once in the public registry with a stable severity, category, producer and meaning.

Canonical source.

v0 hard experiment — responsive card

This fixture is the first architecture falsification test.

Required authored features

• component Card with nested Button component;
• enum variant and boolean state;
• color, spacing and radius token bindings in the profile-0 token model;
• responsive layout changing from one-column to split layout;
• intrinsic text and a vector icon;
• hover/pressed state metadata;
• one opaque vendor.probe extension unknown to an intermediate implementation.

Round-trip path

NUIF reference editor → HTML/CSS adapter → source edit synchronization → NUIF → neutral intermediate editor → NUIF.

Figma/Penpot adapters may be inserted as additional targets, but no vendor tool is required for the core proof.

Success criteria

• 100% stable semantic entity/component IDs on NUIF-native cycles;
• 100% token-reference preservation where target can represent tokens;
• opaque extension bytes survive unchanged;
• resolved boxes at 360/768/1440 px remain within declared tolerance after representable round trips;
• no silent fidelity downgrade;
• a padding/token/text edit patches only the corresponding source region plus unavoidable formatter changes;
• canonical encoding is byte-stable after decode/encode;
• replaying the same operation log from the same base yields the same canonical hash.

Automated baseline

Generate the deterministic package fixture with nuif fixture v0-responsive-card <output.nuif>. Run editor-trial.jsonl through nuif-editor --headless --script ... --document <output.nuif> to exercise entity-bound selection, semantic edits, undo/redo, complete mutation-log replay, package-preserving save and a deterministic snapshot. Snapshot directories contain the real input.nuif package and a generated input.nuif.json inspection projection. nuif trial <seed> <iterations> [snapshot-interval] drives replay, inversion and text/CBOR fixpoints on every patch, with responsive-layout/CPU-rerender checks at the requested interval. cargo xtask gate-b runs 10,000 patches with a raster interval of 100.

After cargo xtask browser-install, cargo xtask gate-c lowers this fixture independently to Taffy and DOM/CSS at 360 × 640, 768 × 768 and 1,440 × 900. The strict 2026-08-29 report records exact agreement for every box across all three engines. cargo xtask gate-g separately compares canonical text, opaque preservation, layout, decoded RGBA and fidelity with the standard-library-only Python implementation.

cargo xtask gate-f-v0 closes the retentive source segment. The model trial retains 181 source correspondences and changes only eight spans for token, padding, text and responsive edits while preserving every other byte and the unknown payload. Its second path edits name and width through the headless semantic editor, synchronizes through the public CLI and requires the imported canonical NUIF bytes to equal the editor output. The profile preserves path and instance identity but does not claim browser path rendering or instance materialization; those limitations remain explicit fidelity rather than weakening the experiment’s model round trip.

Canonical source.

Penpot foreign fixture

fixture.penpot is generated by the official @penpot/library 1.1.0 package from generate.mjs. It supplies foreign-producer evidence for the bounded nuif-penpot-v3-0 package reader. The fixture contains one file, one page, one board, one rectangle, one circle and one literal text shape. The org-nuif plug-in data on the text shape carries the pinned font identity that Penpot’s literal package member does not otherwise express.

Regeneration requires Node.js and network access for npm ci:

cd conformance/foreign/penpot
npm ci --ignore-scripts
npm run generate

The generator fixes JavaScript time before loading the ZIP writer and supplies all mapped UUIDs. The gate compares decoded member semantics and exact retained payloads; it does not treat the ZIP envelope timestamp or compression stream as a semantic format guarantee.

Primary locator: Penpot repository library/README.md, library/src/lib/builder.cljs and library/src/lib/export.cljs, retrieved 2026-08-30: https://github.com/penpot/penpot/tree/develop/library.

Canonical source.

Profile-0 render fixtures

profile-zero-v1.json defines the exact solid-paint CPU subset by value: encoded-sRGB color, scaled rectangle edge inclusion, Zeno 0.3.3 grayscale ellipse masks and integer source-over composition on an opaque-white RGBA8 target.

cargo xtask gate-d-render repeats every scene, raw-RGBA raster and PNG artifact; compares committed scene/pixel SHA-256 baselines; rejects out-of-range colors; and verifies property-attributed fidelity for path, image, instance, unknown-kind and document/entity extension data. PNG hashes are reported but are not blocking because a lossless compressor can change bytes without changing pixels. The recorded rectangle and ellipse scene/pixel hashes reproduce on macOS/aarch64, Linux/aarch64 and Linux/x86_64. This matrix does not imply equality on untested platforms.

The fixture does not claim support for gradients, strokes, arbitrary paths, images, masks, effects or component-instance materialization. Those inputs are outside render profile 0 and remain explicit in fidelity reports.

Canonical source.

Profile-0 text shaping fixtures

harfbuzz-14.4.0-ahem.json is an independent shaping and outline oracle captured with HarfBuzz 14.4.0 and the exact Ahem 1.50 bytes embedded by font-test-data 0.7.0. The font SHA-256 is f0a92cd0cc45735591c9b5b1fa8aecd5194e8dc518895ca22af94a46c23550dc.

The fixture compares glyph identifiers, Unicode-scalar cluster indices, offsets and advances with glyph names disabled. It also compares unhinted Skrifa 0.46.2 outlines in signed 26.6 font units with five normalized hb-vector paths; normalization removes hb-vector’s redundant explicit line to the contour start before close. cargo xtask gate-d-text repeats both stages, exercises both writing directions, checks typed font failures and writes target/text-pinning-report.json.

The CPU rasterizer uses the same unhinted outlines, pinned Zeno 0.3.3 8-bit grayscale nonzero-fill masks, a fixed 800-font-unit first baseline and alpha composition over encoded sRGB channels. Three scene/raw-RGBA context hashes reproduce on macOS/aarch64, Linux/aarch64 and Linux/x86_64. PNG hashes diagnose deterministic artifact encoding but do not gate pixel conformance. Profile 0 shapes CR/LF/CRLF/NEL/LS/PS hard lines independently, positions baselines by the authored line height, aligns to the inline-start edge and clips without automatic soft wrapping. The report classifies this deliberately bounded text profile as lossless; full UAX #14 soft wrapping is not claimed.

Canonical source.

Benchmark suite

NUIF separates portable release budgets from controlled-hardware statistical measurements. cargo xtask performance always runs the portable release profile, then executes every Criterion path once with Criterion’s test mode. That smoke execution detects stale fixtures, panics and dependency drift without pretending that a shared CI runner provides stable throughput measurements. Successful execution writes target/criterion-smoke-report.json; portable latency and allocation budgets remain in target/performance-profile-report.json.

For controlled measurements, run:

cargo bench --locked -p nuif-conformance --bench profile_zero
cargo bench --locked -p nuif-conformance --bench system_surfaces

Keep the machine idle, record its CPU, operating system, power mode, toolchain and source revision, and compare saved Criterion baselines only on equivalent hardware. Do not turn one noisy percentage into a merge gate. A proposed optimization must preserve the conformance gates first and then improve a predeclared workload over repeated samples.

Coverage

profile_zero measures validation, canonical text/CBOR, patch application, local transactions, undo/redo, layout, scene construction, CPU rasterization and complete SDK snapshots over bounded fixture scales.

system_surfaces measures direct SDK text/CBOR/package calls, structural and authorized package-capability paths, entity queries, both collaboration materializers, package/resource profiles and every integrated adapter profile:

• HTML/CSS profile 0 and full-v0 import/export/synchronization;
• SVG, DTCG, React and Svelte import/export/synchronization;
• Penpot native/foreign package import, export and no-op/edited synchronization;
• Figma snapshot import and mutation-plan generation;
• web accessibility and finite behavior projection.

Figma and browser profiles measure pure mapping only; live host latency belongs to a separately versioned host trial. WASM, MCP and CLI process startup belong to their cross-surface package gates, because mixing process launch with in-process Criterion samples would obscure both costs. Affinity, Canva, SwiftUI, Compose and Flutter have no integrated executable profile and therefore no benchmark claim. The Affinity draft composes the already measured SVG adapter with a separately timed human/live-host trial; the Canva draft must gain a pure mapping gate before it enters Criterion.

Optimization rule

Benchmark setup constructs and validates fixtures before timing. Measured code must consume inputs through black_box, and mutation/history measurements use batched clones so state does not leak between samples. A faster result is not accepted if it changes canonical bytes, diagnostics, fidelity, resource policy or operation atomicity.

Canonical source.

Test-harness architecture

Status: profile-0 baseline, deterministic nuif-package-0, narrow cross-decoder nuif-png-rgba8-0, Gate C browser/Taffy, Gate D text/render, Gate E complete editor authoring, bounded and full-v0 Gate F HTML/CSS synchronization, SVG/DTCG/Penpot/React/Svelte retentive adapter gates, the pure Figma snapshot mapping gate, the three-engine bounded web-accessibility projection, the Rust/Node bounded behavior state-machine differential, nuif-wasm-api-0, Gate G independent v0 reproduction, Gate H property-register and existing-tree convergence, and a bounded five-target sanitizer fuzz suite are implemented. Bounded browser/screenshot capture and reconstruction contracts, typed per-example/corpus reconstruction evaluation, a group-isolated corpus-manifest auditor, canonical provider manifests, pinned LDR-FLIP diagnostics, the typed confidence-calibration evaluator and the pinned local live-Chromium segment have executable evidence; their portable cross-provider accuracy corpus is not yet a release gate. Empirical perceptual thresholds and distributional reconstruction comparison, concurrent entity creation and broader foreign-runtime trials remain planned. This document specifies how round-trip trials run unattended, fail reproducibly, minimize themselves and report in machine-readable form. Evidence is cited by research record identifier.

Goals

1. Every conformance suite in conformance/PLAN.md runs from cargo test --workspace and from nuif CLI commands without a display or GPU.
2. A failing seeded trial is reproducible from its seed, iteration, sampled viewport, snapshot decision, source revision and minimized semantic operation sequence. When a report path is supplied, the CLI also reduces the base document and atomically emits a sibling regression-fixture directory.
3. Oracles are explicit: reference implementation, alternative implementation, self-consistency (metamorphic relations) and declared assertions. No oracle is a human.
4. The editor is a client of the same engine and harness; nothing is testable only through the GUI.

Workspace layout

Cargo.toml                 workspace; [workspace.lints]; resolver = "3"; Cargo.lock committed
rust-toolchain.toml        pinned toolchain (see ADR 0006 for the MSRV decision)
.cargo/config.toml         [alias] xtask = "run --package xtask --"
crates/
  nuif-core                canonical model
  nuif-protocol            operations, transactions, patches, inverses
  nuif-layout              evaluation context and profile-0 reference evaluator
  nuif-render              render scene, backends (CPU reference; Vello interactive)
  nuif-codec               nuif-text-0, nuif-cbor-0, canonicalizer, migrations
  nuif-package             deterministic bounded .nuif ZIP package and resource policy
  nuif-media               bounded declared media decoders; narrow PNG RGBA8 profile
  nuif-font                bounded static OpenType inspection and package policy
  nuif-reconstruct         typed observations/proposals and finite correction loop
  nuif-capture             browser-source and strict screenshot capture baselines
  nuif-query               semantic queries
  nuif-api                 Engine trait, report types, session driver
  nuif-wasm                byte-oriented browser/Node binding over nuif-api
  nuif-cli                 command surface; JSON output; stable exit codes
  nuif-testing             seeded trials, hostile-input measurement, v0 fixture, direct Taffy/Chrome oracles, reducer and reports
apps/
  editor                   headless driver plus tested Masonry GUI shell; package-preserving I/O
conformance/
  Cargo.toml               executable profile-0 conformance package
  src/lib.rs               v0 responsive, extension, seeded-trial and parity assertions
  fixtures/<suite>/<id>/   input.nuif, context.toml, expected.*, meta.toml
  fonts/                   pinned fonts referenced by fixtures; no system fonts
  generated/               planned persisted browser cases; runtime Gate C cases are seed-derived
fuzz/                      pinned cargo-fuzz package; five bounded production-core targets
xtask/                     implemented research/verify/Gate B/Gate C/hostile-input/editor loop
tools/
  research/                record validator
  git/                     commit lint

Rationale: harness = false suites enumerate fixture directories at run time and remain compatible with cargo nextest (libtest-mimic-and-data-driven-fixtures); shared test support lives in a normal crate so the editor, the CLI and the suites use one generator and one reducer; xtask replaces shell scripts so generation is reproducible under --locked (cargo-workspace-xtask-and-ci-layout).

Fixture format

One directory per case. Files:

Persisted expectation regeneration remains a planned extension and will use one variable, NUIF_UPDATE_EXPECT=1: a missing expectation fails the case and writes expected.*.new, and generated suites are replaced wholesale rather than hand-edited (taffy-and-yoga-browser-generated-tests). The implemented Gate C runner instead derives cases from a recorded seed, measures all three engines in one run and stores raw observations in its report; it has no stale golden file to update. Per-asset metadata for future persisted suites follows the sample-asset corpus model (gltf-validator-and-sample-assets).

Determinism controls

• Seed: every implemented generator draws from one xorshift PRNG seeded per trial; nuif trial <seed> <iterations> [snapshot-interval] [report-path] records the seed and failing iteration and optionally persists the JSON report (deterministic-simulation-testing).
• Time and randomness: profile 0 has no time-dependent engine semantics; the editor uses monotonically assigned transaction identifiers, and generated values come only from the trial PRNG. Virtual time is required before behavior/animation work begins (masonry-xilem-and-linebender-test-harness).
• Floating point: canonical text follows RFC 0005’s stated shortest-digit layout and canonical CBOR follows RFCs 0005/0008. Gate C records each fixture’s observed Taffy/browser maximum and rounds it upward to 0.01 px, capped by the 0.1 px foreign-engine safety bound. Exact agreement retains zero tolerance; no aggregate bound silently replaces the fixture values.
• Fonts: the fixture uses the content-addressed Ahem 1.50 bytes (f0a92c…550dc), HarfRust 0.13.3, Unicode 17.0.0 and Unicode-scalar cluster indices. Eight LTR/RTL goldens were independently captured with HarfBuzz 14.4.0. Five unhinted Skrifa 0.46.2 outlines match normalized hb-vector paths in signed 26.6 font units. Pinned Zeno 0.3.3 8-bit grayscale nonzero-fill coverage produces the same three scene and raw-RGBA hashes on macOS/aarch64, Linux/aarch64 and Linux/x86_64. CR/LF/CRLF/NEL/LS/PS hard-line layout is exact; profile 0 does not request automatic soft wrapping (text-rendering-reproducibility).
• Threads: the current suites have no shared mutable global state and pass under libtest’s normal parallel execution.
• Environment: CI uses --locked and pinned Rust 1.98.0; the separate MSRV job checks 1.96.0.

Oracles by suite

Trial loop

The target loop is shared conceptually by CLI, CI and editor automation. Profile 0 currently implements generation, replay, inverse, canonical encodings, responsive layout, CPU rerender, operation ddmin, document-aware subtree/scalar reduction, choice-stream shrinking, atomic minimized-fixture writing, adapter-specific round trips, fuzz choice streams and the Gate C foreign layout matrix.

trial(seed, profile):
  d0   := load(fixture) | generate(seed, profile)          # swarm-selected feature subset
  log  := generate_ops(seed, d0, reference_model)          # preconditions checked against the model
  d1   := apply(log, d0)                                   # engine
  assert replay(log, d0) == d1                             # determinism
  assert apply(inverse(log), d1) ≡ d0                      # inversion
  for ctx in context_matrix: L[ctx] := layout(d1, ctx)     # resolved snapshots
  for R in metamorphic_relations: assert R(d1, L)          # nine relation classes
  for A in adapters: assert roundtrip(A, d1) with report   # fidelity accounting
  bytes := encode(d1); assert canonical(bytes)             # fixpoint
  scene := lower(d1, L[ctx0]); img := raster_cpu(scene)    # tier 1 reference
  compare(img, expected | reftest_pair)                    # oracle by tier
  on failure: reduce(seed, d0, log) -> fixture; write report

The implemented reducer first runs complement-based ddmin over semantic operations. Its document pass removes entity subtrees in progressively finer chunks, prunes containment and relation edges, and relies on full model validation to reject dangling component, token or asset references before the interestingness predicate runs. It then reduces relations, tokens, assets, extension namespaces and known scalar fields; unknown-kind opaque bytes remain fixed. The choice-stream pass deletes contiguous regions, exhaustively lowers bytes and redistributes adjacent numeric choices toward shortlex order. Accepted candidates are content-hash memoized. A fixture writer atomically creates input.nuif.json, operations.json, reduction.json and fixture.json and refuses an existing destination. cargo xtask reduction-profile exercises all of these paths and archives the report and emitted fixture (delta-debugging-and-test-case-reduction, property-based-testing-state-machines).

Report schema

One JSON document per run, modelled on the glTF Validator report (gltf-validator-and-sample-assets) and required by apps/editor/QA.md item 10:

{
  "schema_version": 1,
  "engine": {"version": "0.0.1", "toolchain": "rustc 1.98.0 (…) ", "source_revision": "…", "dirty": false},
  "profile": {"capabilities": ["model", "operations", "layout-profile-0", "render-cpu-profile-0"], "encodings": ["nuif-text-0", "nuif-cbor-0"]},
  "trial": {"seed": 42, "iterations": 10000, "operations_per_iteration": 16, "snapshot_interval": 100},
  "contexts": [{"viewport": [360, 640], "canonical_hash": "nuif-cbor-0:sha256:…", "layout_boxes": 8, "render_commands": 4}],
  "issues": {"errors": 0, "warnings": 0, "information": 4, "hints": 0, "messages": ["…"]},
  "fidelity": [{"context": [360, 640], "entity": "…", "status": {"class": "approximated", "reason": "…"}}],
  "artifacts": [],
  "reproduction": null
}

Diagnostic codes are stable strings emitted in machine reports; severities serialize as error, warning, information or hint, and command exit status depends only on errors. The canonical diagnostic code registry records every model, layout and trial code, default severity, category, producer and stable meaning. cargo xtask diagnostic-audit blocks undocumented, duplicated, stale or reordered entries.

The hostile-input experiment writes a separate target/hostile-input-report.json because allocator and elapsed-time measurements are process-level rather than document fidelity entries. It records every input size, expected/observed error class, allocation counters, retained bytes, elapsed microseconds, limits, warmup, allocator method, toolchain and platform. cargo xtask hostile-inputs regenerates it and CI uploads it as hostile-input-report.

The editor hostile-interaction experiment writes target/editor-hostile-input-report.json. Its release runner rejects zero, one-over-edge and maximal snapshot requests before raster allocation; accepts the exact one-dimensional edge boundary; rejects non-finite size, position and spacing values plus malformed paint without mutation; and checks missing selection/node errors, atomic multi-operation failure, empty history, redo invalidation and exact patch-log replay. Unit tests additionally exercise bounded script reads, per-line limits, command limits and malformed-line attribution. cargo xtask editor-hostile-inputs is blocking and CI archives the report.

The reduction experiment writes target/reduction-profile-report.json plus target/reduction-profile-fixture/. Its fixed interestingness predicate reduces the complete responsive card to the valid three-entity ancestor path, proves component references cannot dangle, reduces a byte choice stream, records every accepted transformation and confirms that the atomic writer refuses overwrite. On a real nuif trial failure with a report path, the same machinery emits <report-path>.reproduction/ using the recorded failure code, viewport and snapshot decision.

The standalone fuzz/ workspace pins nightly 2026-08-28, cargo-fuzz 0.13.2 and libfuzzer-sys 0.4.13 without adding sanitizer dependencies to release packages. cargo xtask fuzz-smoke regenerates target-specific valid seeds from production fixtures, then runs raw codec, package/archive, resource-decoder, static-source-adapter and typed-operation targets with explicit input, timeout, allocation and RSS limits. The operation target maps bytes to valid production operations rather than maintaining a second document grammar; parser targets retain malformed bytes. CI runs 512 inputs per target under AddressSanitizer and archives target/fuzz-smoke-report.json. Crash bytes remain local until reduced and promoted to a named regression fixture.

The 10,000-patch Gate B run writes target/gate-b-report.json. cargo xtask all also installs or reuses the locked browser oracle and writes target/verification-manifest.json on success or at the first failing step. The manifest records revision, dirty state, toolchain, completed steps and the presence of every expected evidence artifact, so CI and autonomous research controllers can make a decision without parsing console output. cargo xtask manifest performs the narrower presence audit on an already-generated evidence set; its manifest is labelled artifact-index, does not claim that it executed any trial, and fails after writing the index when an artifact is absent.

The adapter inventory audit writes target/adapter-coverage-report.json before the executable gates. cargo xtask adapter-audit requires all twelve advertised targets to have a reviewed or verified research-record path, next bounded profile and explicit exclusion boundary. Integrated entries must resolve crate, profile and routed gate paths; researched and externally constrained entries must not claim executable directions. This is coverage and claim-boundary evidence, not foreign-runtime conformance.

The layout-differential experiment writes target/layout-differential-report.json. It records the source revision, dirty state, toolchain, exact Taffy and browser pins, launch flags, seed, case source, viewport, raw box maps, observed foreign delta, fixture-local assertion value and every typed divergence. Missing browsers, version drift, evaluator defects, Taffy/browser differences beyond the measured bound and unclassified differences fail cargo xtask gate-c. Schema-loss records remain available for inputs outside a declared profile, but the bounded explicit-Grid cases permit no schema-loss exemption.

The text-pinning experiment writes target/text-pinning-report.json. It records the exact font, shaper, Unicode, outline extractor, rasterizer and independent HarfBuzz oracle pins; expected and observed glyph/outline strings; source/toolchain/platform identity; hard-break/no-soft-wrap semantic trials; repeatability and committed scene/raw-RGBA baselines at three evaluation contexts; PNG artifact hashes; and negative missing/malformed-font cases. cargo xtask gate-d-text fails on any pin, golden, semantic, scene/pixel baseline, repeatability or negative-case mismatch. A PNG-reference mismatch is diagnostic because the lossless compressor is outside the pixel boundary. The bounded text profile is lossless and its scene/pixel hashes agree on macOS/aarch64, Linux/aarch64 and Linux/x86_64.

The independent-reproduction experiment writes target/gate-g-report.json plus canonical text, layout and PNG artifacts under target/gate-g-independent. cargo xtask gate-g generates a real package and reference artifacts at three viewports, exports one generated input.nuif.json projection, runs the standard-library-only Python document-profile implementation’s unit suite, then compares independently computed canonical document bytes, opaque preservation, boxes, decoded RGBA and fidelity. The Python implementation deliberately does not claim package parsing and does not import, link or invoke any Rust workspace package; only the outer differential harness invokes both implementations.

The render-profile experiment writes target/render-profile-report.json. It fixes every supported paint input by value, repeats rectangle and ellipse scenes/raw-RGBA rasters/PNG artifacts, rejects out-of-range sRGB channels, and requires entity/property pointers for unsupported path, image and instance kinds plus preserved document/entity extensions. cargo xtask gate-d-render fails on any scene/pixel baseline, repeatability, validation or fidelity-attribution mismatch; cargo xtask gate-d runs both Gate D reports.

The narrow image-resource experiment writes target/image-resources-report.json. cargo xtask gate-i-image compares exact RGBA output from png 0.18.1 and independently implemented zune-png 0.5.2 across all row filters with absent/valid sRGB, preserves exact encoded bytes through package fixpoint and an unrelated edit, repeats resource-aware scene and CPU raster output, and rejects unsupported, corrupt and one-over cases. The report explicitly excludes broad PNG colour/metadata support, non-identity transforms, GPU/cross-platform image reproduction and non-PNG formats.

The narrow font-resource experiment writes target/font-resources-report.json. cargo xtask gate-i-font compares the profile’s Skrifa interpretation with a committed hb-info 14.4.0 capture of metrics, family, tables and Unicode coverage for the exact pinned Ahem bytes, while three more static TrueType fixtures exercise acceptance. NUIF-owned sfnt, checksum and OS/2 validation remains ahead of Skrifa. The gate proves package byte fixpoint and resource retention, mutates metadata and embedding evidence, distinguishes six portability outcomes, and rejects synthetic malformed cases plus real TTC, CFF, variable, COLR, bitmap, CBDT and sbix inputs. The report explicitly excludes TTC, CFF/CFF2, variable, color, bitmap, SVG and WOFF/WOFF2 fonts; it does not claim shaping/raster equivalence or that technical flags grant redistribution rights.

The HTML/CSS retentive experiment writes target/html-sync-report.json and target/html-sync-output.html. It pins Tree-sitter and both grammars, exactly re-imports the declared subset, repeats synchronization, checks the complete unchanged-byte complement of six text/token/padding edits, preserves injected comments/unmapped markup and requires typed stale-span, unsupported-property and one-over-size failures. cargo xtask gate-f is blocking; the bounded profile and its non-claims are specified in adapters/html-css/PROFILE.md.

The full-v0 follow-on writes target/html-sync-v0-report.json, target/html-sync-v0-output.html, target/html-sync-v0-editor-report.json and target/html-sync-v0-editor-output.html. cargo xtask gate-f-v0 checks 181 source correspondences, the unchanged-byte complement of eight model edits, exact opaque preservation and typed negative cases, then drives a semantic editor name/width edit through CLI synchronization and CLI import to byte-identical canonical NUIF. Target visual limits and arbitrary-CSS non-claims are specified in adapters/html-css/V0-PROFILE.md.

The SVG retentive experiment writes target/svg-sync-report.json, a direct synchronized SVG and edited canonical document at target/svg-sync-edited.nuif.json, plus separate public-CLI synchronization report and SVG. cargo xtask gate-svg checks exact import/export, repeatability, the unchanged-byte complement of seven accessibility, paint, geometry and text edits, preserved comments and metadata, and typed unsupported-property, structural, stale-span, derived-geometry, DTD, XML-node and byte-limit cases. The CLI bridge exports a package fixture, synchronizes from the explicit bare-document projection and requires byte-identical canonical document re-import. The mapped SVG 2 subset and arbitrary-SVG non-claims are specified in adapters/svg/PROFILE.md.

The DTCG scalar-token experiment writes target/dtcg-sync-report.json, a direct synchronized token file and edited canonical document at target/dtcg-sync-edited.nuif.json, plus separate public-CLI synchronization report and token file. cargo xtask gate-dtcg checks exact import/export, NUIF Integer/Real discrimination inside DTCG number, repeatability, the unchanged-byte complement of eight name/type/value/metadata edits, and root/token extension retention. Duplicate members, aliases, undeclared standard members, excessive JSON depth, one-over token count, one-over source bytes, unsupported values, structural changes and stale spans are typed failures. The CLI bridge requires byte-identical canonical document re-import. The mapped DTCG 2025.10 subset and token-model limitations are specified in adapters/dtcg/PROFILE.md.

The Penpot v3 package experiment writes target/penpot-sync-report.json, a synchronized Penpot package and edited canonical NUIF document at target/penpot-sync-edited.nuif.json, plus separate public-CLI synchronization report and Penpot package. cargo xtask gate-penpot imports the fixture produced by official @penpot/library 1.1.0, checks deterministic export and byte-exact no-op archive retention, applies eight mapped JSON scalar edits, preserves untouched member payloads plus injected opaque binary/JSON data, and requires exact canonical document re-import. Unsafe paths and one-over package/member limits are typed failures. The library importer additionally rejects excessive count/expansion/ratio/depth/value cases, duplicate names, directories, symlinks, encryption and unsupported compression. The mapped package subset and compact/components/libraries/interactions non-claims are specified in adapters/penpot/PROFILE.md.

The static React JSX experiment writes target/react-sync-report.json, a synchronized JSX module, an edited canonical document and separate CLI bridge artifacts. cargo xtask gate-react uses Tree-sitter JavaScript byte ranges but never evaluates JavaScript. It checks 21 correspondences, 11 mapped edits, the exact unchanged-byte complement, repeated output, typed stale/structural/profile failures and eleven excluded or hostile sources, including the one-over mapped JSX depth case. The intrinsic-only mapping and runtime non-claims are specified in adapters/react/PROFILE.md.

The static Svelte experiment writes target/svelte-sync-report.json, a synchronized component, an edited canonical document, separate CLI bridge artifacts and target/svelte-compiler-oracle-report.json. cargo xtask gate-svelte checks 21 correspondences, 11 mapped edits, exact unchanged-byte complement preservation, repeated output, typed stale/structural/profile failures and 13 excluded or hostile sources. It then uses the exact npm lockfile with lifecycle scripts disabled and requires official svelte/compiler 5.57.0 to parse in modern-AST mode and compile both direct and CLI output without warnings. Tree-sitter owns retained byte ranges; the official compiler remains a separate semantic oracle. Runtime rendering, component CSS and executable template semantics are explicit non-claims in adapters/svelte/PROFILE.md.

The Figma pure-mapping experiment writes target/figma-snapshot-report.json. cargo xtask gate-figma repeats the normalized snapshot bytes, maps the exact visible/opaque/fixed-size subset in both directions through the public CLI, records deterministic repair for portable identity, reports hidden/transparent/effect/variable properties and rejects duplicate host IDs plus the byte limit plus one. It does not load a page, create a node, mutate a host document or test undo inside Figma; those remain live-host requirements in adapters/figma/PROFILE-DRAFT.md.

The WebAssembly cross-surface experiment writes target/wasm-conformance-report.json and generates Node and direct-browser packages. cargo xtask gate-wasm pins wasm-bindgen 0.2.127, initializes the direct-browser target in pinned Chrome, runs the generated Node ABI through canonical text/CBOR, validation, atomic patch and history paths, and requires the output bytes to equal the native CLI after the same patch. It also checks stale, malformed and one-over-byte failure atomicity and an empty authority declaration. Browser layout, WASI and vendor plug-in behavior remain separate trials.

The MCP cross-surface experiment writes target/mcp-conformance-report.json. cargo xtask gate-mcp launches the real stdio binary, opens the 2026-07-28 stateless lifecycle with server/discover, and sends complete metadata on every valid request. An independent Python driver checks the exact four-tool set, JSON input/output schemas, side-effect annotations, typed errors, connection survival after a rejected request and a one-over 4 MiB frame. Canonicalization and atomic patch output must be byte-identical to the native CLI. Twenty-five repeated validation calls record wire median, p95 and maximum latency with a catastrophic two-second p95 budget; this smoke distribution is not a controlled throughput benchmark.

The performance gate follows the same distinction. cargo xtask performance records portable release-mode latency/allocation budgets for catastrophic regressions and executes both Criterion suites once in test mode. The controlled-hardware suites cover core scaling, resources, package-capability negotiation and every declared direction of all ten integrated adapter profiles. Statistical before/after measurements, machine controls and explicit exclusions are defined in BENCHMARKS.md; shared-runner timing noise is not a merge threshold.

The collaboration register experiment writes target/collaboration-report.json. cargo xtask gate-h exhausts all 5,040 deliveries through operation-set and replica-log materializers, checks multiple merge orders and duplicate delivery, requires property-attributed multi-value conflicts and inspects canonical text for leaked replica state. Structural operations still fail before register-profile ingestion.

The separate existing-tree experiment writes target/collaboration-structure-report.json, exhausts 5,040 deliveries of seven move/delete/cycle/stable-anchor changes through sorted-set and incremental rollback/replay materializers, requires one-parent/acyclic checkpoints plus explicit move, deletion, cycle and anchor conflicts, and runs a 4,096-change release scaling guard. tools/automerge-oracle uses pinned @automerge/automerge 3.4.1 to merge the seven immutable operation records in different orders and through save/load, writing target/collaboration-automerge-report.json. This is foreign transport evidence; Automerge does not provide the NUIF tree materializer. Both executable boundaries are specified in crates/nuif-collab/README.md and spec/10-collaboration-profile.md.

The capture/reconstruction contract experiment writes target/capture-reconstruction-report.json. cargo xtask capture-baselines uses fixed browser-provider and strict PNG inputs to exercise repeatability, resource identity, query-secret redaction, evidence classes and omissions, typed atomic proposal application, flat-copy rejection, observation codec fixpoints, calibration interpolation/selective review and finite loop stops. The correction-loop fixture now exercises an explicit successful objective threshold; the library also reports no_improvement when a fresh candidate is rejected, while repeated canonical state remains a separate terminal result. The report carries explicit non-claims for live browser capture, OCR/model accuracy, a broad or held-out corpus, independent evaluation and training.

The reconstruction-evaluation contract writes target/reconstruction-evaluation-report.json. cargo xtask reconstruction-evaluation computes and validates the complete typed nuif-reconstruction-evaluation-0 per-example family over one deterministic synthetic fixture. It keeps exact rate evidence, nullable unavailable resource measurements and suite-specific resource claims, and asserts that one local pixel difference and one missed element remain independently visible. It also rejects inconsistent derived rates and edit-distance work beyond its bound. A three-example nuif-reconstruction-evaluation-aggregate-0 fixture proves input-order independence, pooled rate arithmetic, nearest-rank p50/p95 and explicit missingness. Aggregation rejects mixed suites, duplicate identities, incompatible calibration/perceptual configurations and mixed currencies. The same gate runs pinned nv-flip 0.1.2/nv-flip-sys 0.1.1 LDR-FLIP at 67 PPD over explicitly opaque sRGB8 input. It requires zero mean for identity and a nonzero bounded mean for one local error, records the implementation, PPD, pooling and platform-sensitivity parameters and refuses transparency or shape ambiguity. FLIP remains diagnostic: the report explicitly disclaims OCR/model accuracy, a real or held-out corpus, empirical perceptual thresholds, statistically calibrated uncertainty and independent evaluation.

The separate confidence-calibration contract writes target/confidence-calibration-report.json. cargo xtask confidence-calibration evaluates typed decision events for text and geometry over disjoint calibration and test groups, includes normal and font-shifted holdouts, computes reliability bins, Brier score, ECE and risk/coverage/AURC, and validates a JSON round trip. Equal-confidence cases are admitted as a group and calibration mappings are monotonic, so input order cannot change selection. The report is a synthetic evaluator smoke test: it does not claim production calibration, model quality, distributional coverage or a rights-cleared corpus.

The separate corpus-integrity contract writes target/reconstruction-corpus-audit-report.json. cargo xtask reconstruction-corpus-audit round-trips a bounded typed manifest and exactly derived audit over adaptation, calibration, validation and test fixtures. The gate injects exact-artifact and origin/template/component/font/resource/ generator/near-duplicate collisions across splits; forbidden adaptation, calibration or evaluation use, screenshot-only source claims, absent near-duplicate assignments, unauditable private captures and derived-count drift must fail. Artifact disclosure and permitted use remain separate. These synthetic declarations prove the checker only: they are not licensed real data, a duplicate detector, a legal interpretation, a representativeness analysis or an independent evaluator.

The provider identity contract writes target/reconstruction-provider-manifest-report.json. cargo xtask reconstruction-provider-manifest canonicalizes a bounded nuif-reconstruction-provider-manifest-0 fixture, requires an exact identity fixpoint and proves that changing model bytes changes the provider identity. Every observation bundle carries the manifests behind its observation and proposal identities; duplicate, malformed, missing and dangling registry entries fail before document mutation. The gate also rejects ambiguous implementation identity, duplicate artifact identifiers, a learned provider without a model card and a released/learned provider without external SPDX 3.0.1 or CycloneDX 1.7 inventory identity. Its learned fixture uses synthetic digests, and its browser/screenshot fixtures identify development source bundles; this is supply-chain contract evidence, not an inventory audit, released model, inference run or accuracy result.

The separate live capture experiment writes target/live-browser-capture-report.json. cargo xtask gate-j-live installs or reuses exact Chrome for Testing 152.0.7977.64 and accepts isolated 360, 768, held-out 900 and repeated 360 px captures through bounded loopback CDP. It allows at most three recorded fresh-profile attempts per viewport and accepts only the exact resource/font fixture. It requires loader-specific load plus image/font readiness, a bounded event-quiet point, stable consecutive screenshots, structured context, exact HTML/CSS/PNG/font/probe body set, actual downloaded-font and accessibility evidence, repeat-identical capture/normalization/screenshot bytes, absence of five exercised transport/storage secret canaries and lower held-out aggregate geometry error from two viewports than the one-viewport freeform baseline. The adapter also enforces aggregate event-byte, command, node, font-use, resource, decode, write-buffer and connected-capture limits; the gate requires the four accepted captures and any recorded retries to finish within 120 seconds. The report explicitly excludes cross-browser/OS, opaque-frame, authenticated-site, canvas/video semantic and reconstruction-accuracy claims.

Editor participation

The editor exposes an in-process session driver (nuif-api) that the harness calls without a window: create/open, apply operation, query accessibility tree, dispatch accessibility action, redraw to a CPU frame and snapshot. The accessibility tree carries entity identifiers (accesskit-semantic-ui-testing), so a test asserts “the selected entity is X” by role and identifier rather than by pixel position. cargo xtask editor-trial authors the complete v0 fixture from an empty document, demands byte identity with the direct generator and replay, and emits target/editor-authoring-report.json plus canonical document/context/layout/scene/CPU-PNG/fidelity artifacts under target/editor-authoring-snapshot. GUI screenshot comparison is limited to shell wiring and uses the same tiers as the render suite with per-OS baselines avoided by CPU rasterization. Gesture tests assert the emitted protocol operations, not canvas pixels.

CI matrix

Non-goals

No GUI pointer automation as an oracle; no per-OS pixel baselines; no hand-edited generated fixtures; no test that depends on network access.

Canonical source.

Profile-zero performance methodology

NUIF uses two complementary performance gates. The portable smoke profile is a release binary that runs on developer machines and shared CI, records latency and allocation evidence, and rejects only catastrophic regressions. The Criterion suite is the statistical comparison tool for controlled hardware. Results from different machines, operating-system states or Rust toolchains are not treated as comparable baselines.

Workloads

nuif_testing::performance_fixture is deterministic, valid, bounded by the profile-zero 8,192-entity resource limit and uses the repository-pinned font. Every sixteenth child is text in mixed workloads. Fixture construction is outside timed sections. Protocol clone cost remains deliberately included because atomic application currently requires an isolated candidate document.

Commands

Run the portable release-mode smoke gate and compile every statistical benchmark:

cargo xtask performance

Run the complete Criterion suites without plotting:

cargo bench -p nuif-conformance --bench profile_zero -- --noplot
cargo bench -p nuif-conformance --bench system_surfaces -- --noplot

On an otherwise idle controlled machine, save a baseline before a change and compare against it afterward:

cargo bench -p nuif-conformance --bench profile_zero -- --save-baseline before --noplot
cargo bench -p nuif-conformance --bench profile_zero -- --baseline before --noplot
cargo bench -p nuif-conformance --bench system_surfaces -- --save-baseline before --noplot
cargo bench -p nuif-conformance --bench system_surfaces -- --baseline before --noplot

Criterion accepts a filter after --, such as -- codec --noplot. Use --profile-time 15 to collect a longer, non-statistical profiling workload for an external profiler. Keep the same power mode, foreground load, toolchain and build inputs for both sides of a comparison.

Local calibration

The first system_surfaces calibration ran on macOS/aarch64, Apple M5 Pro, rustc 1.98.0, with 20 Criterion samples, one second of warm-up and two seconds of measurement per case on 2026-08-30. These values establish workload plausibility and one optimization comparison; they are not portable release budgets.

• Stable-ID lookup at 8,192 entities measured 18.5–19.2 ns; a complete kind scan measured 19.2–19.5 µs.
• HTML/CSS, SVG and DTCG synchronization measured 226.7–228.0 µs, 189.7–190.5 µs and 55.5–55.8 µs respectively for their declared fixtures.
• Penpot native export measured 108.3–109.2 µs, native import 79.3–80.2 µs, official-library import 98.3–99.1 µs, a two-scalar synchronized rebuild/re-import 93.9–94.6 µs, and byte-exact no-op synchronization 2.85–2.87 µs. These figures use the 7,855-byte native and 5,439-byte foreign fixtures rather than a large production design.
• The matching allocation-instrumented smoke run now covers 50 cases. The nine resource-path cases add PNG structure/decode, static-font inspection, image and font package encode/decode, resolved scene lowering and a 256x256 image raster. On the same machine, font inspection measured a 0.67 ms median and about 1.12 MiB allocated; font package encode/decode measured 1.05/0.89 ms and about 1.41/1.38 MiB. The 96-byte image fixture is deliberately a boundary smoke case rather than a throughput claim; Criterion owns controlled comparisons and larger media corpus work remains explicit.
• Package encode originally serialized the same 1,024-entity document five times while constructing and then validating its manifest. Reusing the one already-validated canonical CBOR buffer reduced measured encode allocation from 56,840,802 to 11,952,738 bytes and invocation allocations from 634,633 to 125,459. Decode now verifies the descriptor against the canonical archive member already accepted by the codec, reducing allocation from 35,525,804 to 13,081,772 bytes and invocation allocations from 384,447 to 129,860. A consecutive smoke run observed encode/decode medians fall from 27.3/18.5 ms to 8.8/9.3 ms, but those latency figures are diagnostic rather than a statistical cross-run claim. Package byte fixpoints, independent ZIP output, canonical hashes and hostile-input checks remained gating postconditions. A follow-on exact-size ZIP preflight reduced encode allocation by a further 509,614 bytes, from 11,952,738 to 11,443,124, without changing the archive; moving decoded blobs into shared ownership instead of cloning them removed exactly the 22,572-byte font and 96-byte image payloads from their respective decode allocation counts.
• Static React JSX export/import/synchronization measured 0.078/0.077/0.235 ms median for the 778-byte declared fixture, allocating about 71/67/244 KiB per invocation and retaining zero. These are parser-boundary calibration values, not React runtime or browser performance claims.
• Static Svelte export/import/synchronization measured 0.053/0.052/0.166 ms median for the 761-byte declared fixture, allocating about 68/64/236 KiB per invocation and retaining zero. Official compiler execution is intentionally outside these production-parser timings and remains a conformance-oracle cost, not an application-runtime benchmark.
• HTML/CSS v0 and the normalized Figma snapshot profile are included in both performance layers. The smoke report derives the complete integrated-profile inventory from adapters/index.json and fails if its benchmark inventory drifts, so a newly integrated adapter cannot silently omit performance evidence. Figma timing covers only the deterministic mapper; plug-in-host responsiveness remains a named live-host boundary.
• Penpot native export and edited synchronization allocated 291 KiB and 246 KiB per invocation; native and foreign imports allocated 215 KiB and 665 KiB, and the no-op path allocated 35 KiB. Every adapter case retained zero bytes after the measured invocation.
• An initial all-Deflate native export was 4,688 bytes and allocated about 4.04 MiB; edited synchronization allocated about 3.99 MiB. Storing native JSON members below 4 KiB increased this small package by 3,167 bytes while reducing those allocations by about 93% and the two Criterion times by about 49% and 52%. Imported compression methods remain retentive, so foreign-package behaviour did not change. The threshold is a profile workload decision, not a general claim that ZIP storage is preferable to Deflate.
• The 1,024-writer operation-set checkpoint measured 4.08–4.15 ms before replacing an all-pairs causal-maximality search with per-replica maximum observed vector contexts. The algorithmically independent replica-log frontier remained separate. A same-process saved-baseline comparison measured 2.51–2.81 ms afterward and Criterion classified the change as a 36.1–40.3% reduction in time (p < 0.05). Exact checkpoint equality, 5,040 delivery permutations and both materializers remain Gate H postconditions.

Interpretation

• Treat the portable budgets as availability limits, not optimization targets. Its JSON artifact is useful for trend inspection and allocation diagnosis, but shared-runner timing noise is expected.
• Require a repeatable Criterion change on the same machine before claiming a small speedup or regression. Inspect both time and throughput across scales; one small fixture can hide an algorithmic regression.
• Preserve canonical bytes, hashes, diagnostics, fidelity records and operation atomicity while optimizing. Performance never relaxes conformance.
• Record allocation changes alongside latency. A time win that creates unbounded intermediate data is not accepted.
• Add a workload only when it has a stable fixture and a clear user-visible operation. Avoid benchmarks that measure fixture setup or debug assertions.

The command design follows the official Cargo benchmark documentation and Criterion’s command-line and configuration guidance. iai-callgrind remains a possible Linux-only instruction-count layer, but is not a portable gate because it requires Valgrind; Criterion and the allocation-instrumented smoke profile cover the current cross-platform need.

Canonical source.

Conformance plan

NUIF conformance is split into independently testable profiles.

Required suites

1. model — stable IDs, containment, graph references, cycle rules.
2. canonicalization — deterministic text/binary representation and hashes.
3. extensions — used/required negotiation and opaque preservation.
4. layout — authored→resolved fixtures across viewport/context matrices.
5. render — normative geometry/paint/text behavior with declared tolerances.
6. operations — patch replay, inversion, preconditions and deterministic results.
7. merge — three-way semantic conflicts and move/reorder cases.
8. provenance — correspondence retention and fidelity diagnostics.
9. adapter — import/export loss reports and foreign-extension preservation.
10. security — parser depth/size limits, malicious assets and renderer budgets.
11. independent-reproduction — a non-reference package parses/writes the fixture and independently reproduces resolved layout, raster and fidelity.

Test techniques

• golden structural fixtures;
• property-based tests for operation sequences;
• fuzz parsers/codecs and path geometry;
• differential layout checks against browser/Taffy where semantics match;
• metamorphic tests such as encode→decode→encode stability;
• deterministic operation replay;
• visual snapshots with perceptual thresholds only where exact pixels are not normative.

A test result must include implementation version, capability profile, fixture ID and evaluation context. Foreign-reference results additionally include exact oracle versions, generator source revision, raw per-engine observations, a fixture-local measured bound and typed classifications for every divergence.

The implemented adapter suite covers nuif-html-css-0, the separately declared nuif-html-css-v0 responsive-card profile, nuif-svg-0 and nuif-dtcg-scalar-0 with exact export/import, byte-local synchronization and property-attributed rejection. Arbitrary web or SVG source, non-scalar DTCG and other adapter targets remain non-conformant until separately declared profiles pass.

The implemented independent-reproduction suite covers the complete v0 fixture in canonical text and the declared profile-0 layout/render subset. The Python standard-library implementation computes its own boxes and pixels, and the harness compares decoded RGBA so PNG encoder behavior is not mistaken for render divergence. This is an in-repository mechanical reproduction, not evidence of external implementation provenance or standards adoption.

Canonical source.

Reference editor research preview

The editor is an executable conformance and research instrument, not the owner of the NUIF data model. Its 0.1.0-alpha.N versions describe application maturity and do not assign a maturity level to the draft specification. The native Masonry shell and headless driver edit NUIF through the same semantic operation API available to the CLI and automated clients.

The executable profile-zero shell provides a file menu for native document import/save, PNG export, and the repository’s declared SVG, HTML/CSS, DTCG, Penpot, static React JSX and static Svelte profile adapters. A foreign import is bounded before parsing, presents its fidelity summary before opening as a new unsaved NUIF document, and leaves the active document untouched when parsing or confirmation fails. A foreign export writes a sibling .report.json fidelity record. The shell also provides page creation, layer and component browsing, identity-backed canvas selection, frame/rectangle/ellipse/path/text insertion, subtree duplication and deletion, undo/redo, evaluation-width presets, zoom, panel visibility and a command palette. The canvas opens with a document-aligned background grid, pixel rulers and explicit px measurement labels; grid and rulers can be toggled independently. Move-tool drags author whole-pixel-snapped freeform positions or same-parent Stack/Flex order, while resolved selection handles author bounded fixed sizes and anchored freeform positions in one transaction. Its inspector authors names, positions, sizing intents, stack/flex layout, gaps, four-edge padding, alignment, bounded explicit Grid tracks/flow/placement/spans, solid fills and pinned-font text. Multi-field Apply is one atomic transaction.

Run cargo run --locked -p nuif-editor to open the native editor from a checkout. The canonical persistent path is cargo xtask editor-install --user --channel source; tagged source uses the alpha channel. Update, doctor, rollback and uninstall remain explicit checkout-owned operations. See INSTALLING.md for the verified source lifecycle and user-owned platform paths. The same editor binary accepts --headless --script <jsonl> with either direct command records or entity-bound action records. Its accessibility surface supports selection plus name, size intent, position, layout spacing, solid fill and text edits; undo/redo patches are logged too, and every run replays the complete mutation log from the opening document and requires the final hashes to match. Document reads share the 16 MiB profile limit; scripts are capped at 8 MiB, 100,000 commands and 64 KiB per line before JSON parsing.

cargo xtask editor-gui-trial drives the real AccessKit nodes of the native shell and derives pointer paths from resolved entity geometry rather than hard-coded screen coordinates. It exercises freeform move, north-west resize, responsive Stack reorder, undo and redo; independently replays the operation log; renders the complete 1280×800 Masonry tree through the CPU harness twice; and requires identical canonical, replay, shell, menu and document hashes. It emits the screenshot, canonical output, semantic-node inventory and machine-readable report under target/editor-gui-trial/. The full shell is specified in UI-SPEC.md; a Svelte 5 shell over WASM remains a later browser demonstration.

Snapshots reject zero dimensions, an edge above 4,096 pixels or more than 16,777,216 pixels before layout or raster allocation. Accessibility and inspector numeric inputs reject non-finite values for fixed, percentage and fit-content sizes, positions, spacing and text metrics. cargo xtask editor-hostile-inputs checks those boundaries together with missing semantic nodes, atomic multi-operation failure, empty history, redo invalidation and complete operation-log replay; it writes target/editor-hostile-input-report.json.

Opening a package is not a capability grant. Packages with no required capabilities remain editable and preserve their verified embedded resources. A package requiring behavior or another capability the reference editor does not implement opens structurally in persistent read-only mode. Selection, inspection, static snapshots and byte-exact Save As remain available; semantic commands, accessibility mutations, undo/redo mutation and a changed package save fail with the exact missing set. cargo xtask editor-hostile-inputs exercises both the driver and save boundary so opaque resources cannot be silently rebound to an unvalidated document revision.

The draft UI-SPEC.md is broader than executable profile zero. Multi-selection, cross-parent/tree drag, Grid/Constraint reorder, persisted aspect-ratio constraints, object smart guides, managed leading-edge resize, in-editor token editing, component authoring, advanced paint/effects, arbitrary foreign formats and non-PNG rendering export remain gated on corresponding model, protocol, layout, adapter or renderer profiles. The shell does not present inert controls for those features.

Use cargo xtask editor-package to build and verify the native package for the host platform, or cargo xtask editor-launch to package and open it without installation. macOS produces NUIF Editor.app, Windows produces a GUI-subsystem executable, and Linux produces a relocatable desktop application directory. Version tags produce five GitHub prerelease archives with checksums and provenance attestations. Those archives are release evidence and an expert opt-in path; developer installation builds locally according to ADR 0009. See INSTALLING.md, PACKAGING.md and docs/VERSIONING.md.

Canonical source.

Reference editor architecture

The editor is a client of the same semantic engine used by CLI/API tooling. The shell technology is decided in ADR 0006 (accepted): a Rust-native shell on Masonry, Vello and AccessKit; the Svelte 5 shell below is retained as the browser demonstration path. The user-interface specification is UI-SPEC.md.

Rust shell (Masonry widgets, AccessKit tree) — or Svelte 5 shell over WASM for the browser demonstration
        │ typed commands/events
        ▼
Rust core (in-process; WASM boundary only in the browser build)
  ├── document store
  ├── protocol/transactions
  ├── layout evaluators
  ├── render-scene builder
  ├── query/diagnostics
  └── codecs
        │
        ▼
renderer backend (WebGPU/Vello experiment)

The UI shell may keep ephemeral selection/viewport/panel state, but authored document state is NUIF state. Canvas gestures MUST translate into semantic protocol operations before mutation.

Package loading has a separate capability boundary. The editor structurally verifies and preserves every package resource, but its declared package capability set is empty until a complete capability-specific authoring and evaluation profile is implemented. A package with any unsupported required capability opens inspectable and copyable but read-only. Both the shared editor driver and package-save boundary reject semantic document changes, preventing an opaque resource from remaining attached to a document revision it was not validated against.

The editor must expose a local automation endpoint or in-process API that mirrors CLI semantics. MCP may be added as an adapter, never as the canonical automation contract.

Canonical source.

Developer installation

NUIF Editor is installed as a user-scoped developer tool built from reviewed source. Apple notarization, Microsoft Store publication and administrator access are not prerequisites for this path. The source checkout is the control plane for install, update, diagnosis, rollback and removal; retain it after the initial installation.

Prerequisites

• Git, Rustup and the Rust toolchain selected by rust-toolchain.toml;
• GitHub CLI (gh) for verified alpha-channel updates;
• the native build prerequisites for the host;
• Linux Fontconfig development files when building on Linux.

On Debian or Ubuntu, install the Linux native dependency with:

sudo apt-get install libfontconfig1-dev

Do not pipe a remote installation script into a shell. Clone an exact release tag, inspect it when required, and build through the checked-in xtask:

git clone --branch <release-tag> --depth 1 https://github.com/refpath/nuif.git
cd nuif
git rev-parse HEAD
cargo xtask editor-install --user --channel alpha

The alpha install rejects a dirty checkout, requires the exact v<editor-version> tag at HEAD, uses Cargo.lock, builds the native package, installs it, and immediately runs editor-doctor. A local research branch uses the source channel:

cargo xtask editor-install --user --channel source

Dirty source is rejected by default. An intentional local experiment can opt in with --allow-dirty; its receipt contains a deterministic working-tree digest as well as the commit revision.

Lifecycle

Run lifecycle commands from any retained NUIF checkout that contains ADR 0009 support:

cargo xtask editor-update --user --channel alpha --check
cargo xtask editor-update --user --channel alpha
cargo xtask editor-doctor --user
cargo xtask editor-rollback --user
cargo xtask editor-uninstall --user

editor-update selects the highest published numeric alpha version. Before it executes release source, it downloads release-manifest.json, verifies the GitHub attestation against refpath/nuif, the release workflow, the tag, the source revision and a GitHub-hosted runner, then fetches that exact tag with Git hooks disabled. The fetched commit must equal the attested revision and remain clean. Updates are explicit; the editor never updates itself while it is running.

The active and previous immutable installations are retained. Rollback only changes the platform integration point and state file; it does not rebuild or contact the network. A later rollback swaps the two versions again.

editor-doctor verifies the managed marker, state and receipt schemas, source and lockfile identities, installed binary digest and reported version, platform integration, and the local macOS ad-hoc signature. Its JSON report also states whether Git, GitHub CLI, Cargo and Rustc are available for a source update.

User-owned paths

Every removable state root and Windows program directory carries a product marker. Existing unrelated files, directories, symbolic links, desktop entries or shortcuts are rejected rather than claimed. --root <absolute-path> places state and integration below an isolated root for CI and disposable testing; filesystem roots are rejected.

Trust boundary

The macOS source install applies and verifies a free local ad-hoc signature. That signature is not Developer ID, notarization or a publisher identity. The Windows source install does not add a certificate or change Defender, SmartScreen or Smart App Control. No lifecycle command disables Gatekeeper, System Integrity Protection or another operating-system security control.

A managed machine may still require an organization-approved signing certificate or device policy. That is an administrator-owned trust decision, not an installation workaround and not a requirement to publish through an Apple or Microsoft marketplace.

Secondary distribution

GitHub archives, their manifests, checksums, SBOM and attestations remain release evidence, reproducibility material and an expert opt-in download path. They are intentionally not the primary developer installation.

A future Homebrew tap should use a source formula. A Nix flake can provide a locked macOS/Linux development environment. A Scoop bucket may provide a convenient user-scoped Windows archive installation, but it still runs the downloaded unsigned executable and cannot be presented as a SmartScreen trust solution.

Canonical source.

Native editor packaging

cargo xtask editor-package builds the release application wrapper, creates the native package for the host platform, runs the packaged executable with --help and --version, hashes the executable and archive, and writes a package-specific manifest plus target/dist/editor-package-manifest.json.

cargo xtask editor-launch rebuilds and verifies the host package and then opens it. On macOS this calls open -n on the .app; on Windows and Linux it starts the packaged application executable.

Packages contain the Apache-2.0 and MIT license files, a scope notice and a package-local manifest. Versioned archives preserve the executable layout and are CI artifacts. Tag builds also become GitHub prerelease assets with package manifests, SHA256SUMS, a CycloneDX software bill of materials, release-manifest.json, and GitHub artifact attestations. The tag and publication contract is defined in docs/VERSIONING.md and ADR 0007.

Downloaded packages are not the canonical developer installation. cargo xtask editor-install --user builds the same package from the retained source checkout and installs an immutable version with a source/build receipt. The explicit update, doctor, rollback and uninstall lifecycle is documented in INSTALLING.md and ADR 0009.

Current alpha archives are unsigned. Code signing, notarization and installer or store publication require platform credentials and remain separate release operations. The archive manifest records the unsigned status. A locally built macOS developer installation is ad-hoc signed after copying and records adhoc-local; that is neither Developer ID nor notarization. Apple and Windows signing requirements are recorded in nuif:research:github-release-delivery-and-provenance and the source-install boundary in nuif:research:developer-source-installation-and-os-trust.

The Linux package expects a graphical Wayland or X11 session, Fontconfig at runtime, and a graphics driver supported by wgpu. Building it on Debian or Ubuntu requires libfontconfig1-dev; CI installs that package before every workspace or editor build. The archive is a relocatable application directory, not a distribution-specific system package. The Windows application wrapper uses the GUI subsystem so a console window is not opened; the separate nuif-editor binary retains its headless/JSONL interface.

The native-editor CI matrix runs the editor check, tests, semantic and visual trial, complete sandboxed install/doctor/uninstall lifecycle, and packaging command on GitHub-hosted macOS, Windows and Linux systems. Each job uploads its archive, package manifest, install receipt evidence, semantic-node inventory and shell screenshot. This is native-host evidence; a successful cross-compilation alone is not treated as platform verification.

The release workflow adds Linux Arm64 and separate macOS Arm64 and x86-64 hosts. It requires five archives and five package manifests before publication. Each release job builds at the tagged source revision, runs the sandboxed lifecycle in strict alpha mode and uses the pinned Rust 1.98.0 toolchain.

Canonical source.

AI/headless QA contract

Status: items 1–8 and 10 have a profile-0 implementation through nuif-api, nuif-testing, nuif and nuif-editor; automatic minimized failure-fixture writing remains partial. The native-shell wiring has a deterministic AccessKit and CPU-render trial.

An automated QA client must be able to perform the following without synthetic mouse input:

1. create/open/save/canonicalize documents;
2. query entities by identity/type/name/relationship;
3. execute semantic transactions and capture inverse/replay logs;
4. evaluate layout at explicit contexts;
5. inspect resolved boxes, text diagnostics and accessibility semantics;
6. render deterministic snapshots;
7. diff canonical documents and resolved snapshots;
8. validate fidelity and extension-preservation assertions;
9. minimize a failing operation sequence into a reproducible fixture;
10. emit one machine-readable report containing inputs, versions, capabilities and artifacts.

GUI automation is reserved for testing shell wiring, focus, pointer/keyboard interactions and browser integration.

The headless client MUST apply the same bounded document reader as the CLI and MUST bound script bytes, line bytes and command count before retaining an operation log. cargo xtask hostile-inputs verifies document-ingestion boundaries; editor unit tests verify the limit-plus-one reader.

Headless and GUI sessions report the package capability negotiation result. If any required capability is unavailable, selection and inspection may proceed, but every semantic transaction and changed package save MUST fail atomically. The no-op package copy remains byte-exact. This boundary is part of cargo xtask editor-hostile-inputs.

cargo xtask editor-trial is the required complete-authoring trial. It starts from an explicit empty document identifier, dispatches only semantic/identity actions, compares canonical output bytes with the direct fixture generator, independently replays the logged patches, validates the result, and archives the full snapshot evidence used by automated and AI-driven iteration.

cargo xtask editor-gui-trial is the supplementary shell trial. It selects an entity and edits name, sizing, position, layout spacing and fill controls through AccessKit Click and SetValue requests, then locates resolved entities through the canvas widget and performs captured freeform move, north-west resize and responsive Stack reorder pointer drags in document coordinates. Movement commits one position operation; the leading-corner resize commits its anchored position and both fixed-size axes in one transaction; Stack/Flex reorder commits one same-parent Move based on resolved sibling centres. All are whole-pixel snapped where applicable, the expected final child order is asserted, and the reorder is exercised by the following undo/redo pair. The runner independently replays every patch, validates the output document, records the semantic tree, captures both the normal shell and the open File menu, requires every native and profile import/export route to be visible, and repeats the run to require identical canonical and pixel hashes. The shell unit tests additionally cover all eight handle geometries, Shift-proportional corner geometry, managed no-op/rejection boundaries, inactive-tool rejection, atomic resize validation, pixel grid/ruler defaults and exact export/import round trips for the declared SVG, HTML/CSS, DTCG, Penpot, static React JSX and static Svelte fixtures. No hard-coded screen coordinate identifies a document entity or handle; the runner derives pointer paths from resolved layout and the canvas transform.

Canonical source.

Reference test editor: user-interface specification

Status: draft specification for the reference test editor. The editor replicates the spatial layout, tool set, property sections and keyboard bindings of the Figma design editor (UI3) as documented in nuif:research:figma-ui3-editor-layout and nuif:research:figma-tools-and-keyboard-shortcuts, without branding, icons, logos, typography or colour values taken from that product. The feature set is limited to what conformance testing, import and export require. Anything not listed here is out of scope; additions require an RFC.

Implementation status: the native application implements the complete interactive surface for currently executable profile-zero properties: native document import/save and PNG export; bounded import and reported export through the declared SVG, HTML/CSS, DTCG, Penpot, static React JSX and static Svelte adapter profiles; history; pages/layers/components browsing; canvas selection, insertion, captured freeform-child movement, Stack/Flex reorder and bounded resizing; subtree duplicate/delete; responsive evaluation-width presets; zoom and interface visibility; a default pixel grid and rulers; command routing; and atomic name, position, sizing-intent, stack/flex spacing/alignment, bounded explicit Grid, solid-fill and pinned-text inspection. Freeform movement previews the selection outline, commits one position operation on release, snaps to whole pixels by default and suspends snapping while Control is held. A Stack/Flex child drag derives the effective axis from resolved sibling geometry, chooses a same-parent insertion point by sibling centres and commits one Move; unchanged order creates no history. Grid, Constraint, cross-parent and instance-child reorder fail closed instead of guessing semantics. Freeform children expose eight resize handles; managed-layout children expose only east, south and south-east handles because leading-edge anchoring would require an ineffective position edit. A resize previews resolved geometry and commits the changed fixed-size axes plus any freeform leading-edge position as one atomic transaction. Shift preserves the starting aspect ratio for corner drags, Control suspends whole-pixel snapping, and roots and non-finite, non-positive or greater-than-1,000,000 px dimensions fail without mutation. Canvas transforms require the Move tool. Grid authoring exposes positive fixed-pixel and fractional track lists, row/column sparse auto-flow, atomic one-based item position and positive spans; it cannot create implicit tracks or exceed profile-zero resource bounds. Each document edit lowers to an invertible protocol operation and is covered by the pointer/AccessKit/replay trial. Foreign imports open a new session after confirmation rather than mutating the current document. Sections below whose data is not in profile zero remain specification targets, not inert or simulated controls—most notably multi-selection, persisted aspect-ratio constraints, managed-layout leading-edge resize, cross-parent/tree drag and Grid/Constraint reorder, component authoring, in-editor token editing, advanced paints/effects, arbitrary foreign formats and non-PNG rendering export.

Native packages whose required capability set is not fully supported open structurally in a persistent read-only mode. Selection, inspection, static snapshot and byte-exact copying remain available, while driver and save-boundary mutations fail with the exact missing identifiers. This avoids silently carrying opaque resources onto a document revision they were not validated against.

Purpose and constraints

1. The editor is a client of nuif-api. Every gesture lowers to protocol operations before any document mutation (apps/editor/ARCHITECTURE.md).
2. The editor is a test instrument. Its state is NUIF state plus ephemeral selection, viewport and panel state.
3. Automated test iterations use the CLI and the in-process session driver, not the GUI. The GUI exists to author fixtures by hand, to inspect import and export results, and to prove that a human-authored fixture and a replayed operation log converge (roadmap phase 5 exit).
4. Layout conventions replicated here are user-interface conventions, not protected expression; names, marks, icons and visual assets are not reproduced (nuif:research:design-editor-ui-conventions-synthesis).

Regions

┌──────────────────────────────────────────────────────────────────────────────┐
│ [A] Top bar: document name · page selector · Minimize UI                     │
├───────────────┬───────────────────────────────────────────┬──────────────────┤
│ [B] Left      │ [C] Canvas                                │ [D] Right panel  │
│ panel         │  rulers · infinite canvas · zoom          │  zoom % · Export │
│  Pages        │  marquee · snapping · smart guides        │  ┌ Design ────┐  │
│  Layers       │  measurement overlay                      │  │ sections   │  │
│  Components   │      ┌───────────────────────────────┐    │  │ (resizable)│  │
│  (resizable)  │      │ [E] Toolbar (floating, bottom) │    │  └────────────┘  │
│               │      │ Move Hand Frame Shapes Pen Text│    │  Diagnostics     │
│               │      └───────────────────────────────┘    │                  │
└───────────────┴───────────────────────────────────────────┴──────────────────┘

Minimize UI collapses A and B; D reappears while a selection exists. Hide UI hides A, B, D and E. Panels B and D are resizable; widths persist per session only. Panel pixel widths are not specified by evidence and are chosen by implementation.

Left panel [B]

• Pages: ordered list of surfaces (NUIF Surface entities); add, rename, reorder, delete.
• Layers: containment tree of the current page; expand and collapse; drag to reparent and reorder; rename inline; visibility and lock toggles; multi-selection synchronized with the canvas.
• Components: local component definitions of the document; drag to instantiate.

Excluded: team libraries, asset search, remote components.

Canvas [C]

• Infinite canvas with independently toggled pixel rulers and a document-aligned background grid. The profile-zero authoring unit is px and is shown in the top bar, status bar and numeric inspector labels. The page background colour comes from the surface.
• Interaction grammar (bindings in the table below): marquee selection from empty space; additive and subtractive selection; hierarchical traversal (child, parent, next and previous sibling); deep selection; duplicate by modifier drag; pan by Space drag or Hand tool; zoom by modifier scroll and by shortcuts (fit, selection, 100 %).
• Snapping to objects and pixel grid with smart guides; suspended while the declared modifier is held. Measurement overlay to the hovered entity while the declared modifier is held.
• Every canvas gesture emits one transaction: move in freeform becomes a transform edit; drag inside a stack becomes a reorder; resize becomes a sizing-intent edit or a fixed size according to the parent family (docs/whitepaper/03-protocol-and-portability.md).

Excluded: comments, cursors of other users, presentation mode, prototype links.

Toolbar [E]

Floating strip centred at the bottom of the canvas. Tools, in order, with their group menus:

The command palette is the keyboard route to every operation and to Import, Export, Validate and Snapshot. Excluded tools: Scale, Section, Slice, Polygon, Star, Arrow, Pencil, Comment, Dev Mode toggle, drawing and illustration tools, AI actions.

Right panel [D]

One tab, Design. Sections appear in this order for a container with a stack or flex family; sections absent for the selected kind are hidden.

1. Header: entity name; Create component; Detach instance (for instances).
2. Position: alignment row (six alignments and two distributions for multi-selection); X, Y; rotation; flip horizontal and vertical; constraints (freeform children only).
3. Layout family: family selector (freeform, stack, flex, grid, constraint); flow direction and wrap; gap; padding uniform or per side; alignment grid. Grid containers additionally expose row/column sparse auto-flow and explicit column/row track lists using compact 120px 1fr syntax. Their children expose one atomic position field (auto or one-based column row) and positive column/row spans. This section replaces the product’s auto-layout section and exposes NUIF families directly.
4. Sizing: W, H; per-axis intent (fixed, intrinsic, fill, fit-content, percentage); min and max; aspect ratio; clip content. Values are plain numbers or token references (see Tokens).
5. Appearance: opacity; corner radius uniform or per corner; blend mode; visibility.
6. Fill: ordered list of solid colour and linear or radial gradient paints; image fill for Image entities.
7. Stroke: colour, weight, alignment, per-side, dash pattern, cap, join.
8. Effects: drop shadow, inner shadow, layer blur, background blur.
9. Typography (Text entities): font family from the pinned font set, weight, size, line height, letter spacing, alignment, text sizing behaviour.
10. Component (definitions): parameters of kind boolean, enum variant, text, instance swap. Instance: parameter values and override reset.
11. States: named interaction states (default, hover, pressed, focused, disabled) with per-state property overrides. This section exists because the v0 fixture requires state metadata; no prototype player is included.
12. Tokens: every numeric or colour control accepts a token reference chosen from the document’s token set; a bound control shows the token name and a detach action. Token sets are edited in a dialog opened from the command palette (DTCG-compatible).
13. Export: format (PNG, SVG, PDF, nuif-text-0, nuif-cbor-0, adapter targets), scale, suffix; Export opens the fidelity report.

Diagnostics: a collapsible list under the sections showing validation, fidelity and layout diagnostics for the selection, produced by nuif-api; each entry links to the entity.

Excluded: Prototype and Inspect tabs, selection colours, styles library, variables modes UI, glass, noise and texture effects, video and pattern fills, layout guides, image cropping, boolean operations, masks, vector networks beyond path editing, version history, branching.

Dialogs

• Import: the File menu selects NUIF, SVG, HTML/CSS, DTCG, Penpot, static React JSX or static Svelte. External input is size-bounded before parsing; text profiles require UTF-8 while the Penpot profile validates bounded ZIP members in memory. A native NUIF package is structurally verified before opening; unsupported required capabilities are listed in the status bar and window title and force read-only inspection. A confirmation dialog shows fidelity-class and correspondence counts before the external imported document replaces the session as an unsaved document. Merge-into-document import is not implemented.
• Export: the File menu selects PNG, SVG, HTML/CSS, DTCG, Penpot, static React JSX or static Svelte. Each external adapter export writes the artefact and a sibling .report.json; a profile mismatch fails before the destination chooser and writes nothing.
• Tokens: token set editor.
• Evaluation context: viewport size presets (360, 768, 1440 px and custom), scale factor, locale, writing direction, theme; the canvas renders the selected context; multiple contexts can be shown side by side for a surface.
• Snapshot: writes the canonical document, the resolved snapshot for the current context and the CPU rasterization to a fixture directory in the harness format (conformance/HARNESS.md).

Keyboard bindings

Bindings reproduce the documented product bindings where verified; entries marked U in the source record are chosen to match common expectation and are not claimed to be product-accurate.

Automation surface

The editor binary accepts --headless --script <file> and either --document <file> or --new-document <id>, then runs a session script against the same nuif-api engine without creating a window (nuif:research:blender-dna-rna-and-headless, nuif:research:unreal-asset-versioning-and-automation). --expect-document makes byte-exact parity blocking; --report and --snapshot-dir write the operation log and canonical/context/layout/scene/CPU-raster artifacts. The JSONL script language contains editor commands and semantic accessibility actions sharing one session.

The nuif-editor-automation feature-gated binary drives the native Masonry tree in process. It dispatches AccessKit actions, captures the matching accessibility tree and CPU-rendered shell frame, replays the protocol log independently and emits a machine-readable artifact set. cargo xtask editor-gui-trial repeats that run and requires identical canonical and pixel hashes. No socket transport is implemented.

Widget identity: every widget bound to a document entity exposes the entity identifier in its accessibility node (author_id), and every control exposes a role and label, so a harness locates “the width control of entity X” by query and sets it through an accessibility SetValue action (nuif:research:accesskit-semantic-ui-testing). No test depends on pixel coordinates of widgets.

Rendering and text

The canvas renders through nuif-render. Interactive rendering uses the Vello backend; snapshots and headless runs use the CPU reference backend so that editor snapshots and conformance references are produced by the same path. Fonts are limited to the pinned set shipped with fixtures; system fonts are not enumerated.

Implementation stack

Decided in ADR 0006 (accepted): Rust-native shell on Masonry (pinned by git revision; Xilem not used) with Vello rendering and AccessKit, replacing the earlier Svelte 5 shell proposal for the reference editor. The canvas lowers NUIF RenderScene to Masonry’s imaging command set; the CPU reference renderer in nuif-render remains the conformance oracle. Toolchain 1.98.0, MSRV 1.96. A browser build through WASM remains a later demonstration target, not the reference editor.

Canonical source.

Adapter inventory

This page is generated from adapters/index.json. The inventory contains 12 host or format targets.

Adapters

External ecosystems are peers around NUIF, not parents of its canonical model.

The first executable adapter is the deliberately bounded nuif-html-css-0 retentive profile. It records concrete byte spans, round-trips its declared container/text/token subset exactly, applies mapped changes without regenerating comments or unmapped regions, and rejects every unsupported semantic change with target/property fidelity.

The follow-on nuif-html-css-v0 profile carries the complete responsive-card model, including responsive rules, component/instance identity, unknown kinds and opaque extensions. Its automated editor bridge proves semantic editor output can patch retained source and return through the CLI to byte-identical canonical NUIF. Path rendering, instance materialization, unknown visuals and arbitrary HTML/CSS remain explicitly outside the target profile.

The separate nuif-web-accessibility-0 projection lowers a ten-role, role-specific Boolean-state and five-relationship subset into inert native HTML and ARIA. A pinned Playwright oracle compares the computed roles, accessible names and supported states of the same eleven-node fixture across Chromium, Firefox and WebKit while retaining host-tree differences separately. It does not synthesize behavior or claim native platform accessibility equivalence.

The one-way nuif-web-behavior-0 projection composes that semantic mapping with the bounded state-machine sidecar. It maps enabled native button/switch activation, hidden visibility and one polite status announcement through a generated finite runtime authorized by its exact CSP hash. Three Playwright engines reproduce every event’s transition, state and retained host effects. Authored JavaScript, behavior import, focus, checkbox/radio mutation and assistive-technology speech remain excluded.

The nuif-svg-0 profile maps one surface, freeform groups, rectangles, ellipses and literal pinned-font text to SVG 2 XML. It retains UTF-8 spans for identity, geometry, paint and accessibility scalars, preserves unmarked XML byte-for-byte during edits and rejects unsupported geometry, paint and structure with typed fidelity.

The nuif-dtcg-scalar-0 profile maps flat DTCG 2025.10 boolean, string and number tokens while preserving NUIF integer/real identity through namespaced metadata. It retains unknown extension bytes through the same CLI synchronization contract as the source adapters. Its deliberately narrow boundary precedes the token-model RFC required for groups, aliases and composite types.

The nuif-penpot-v3-0 profile maps one Penpot v3 package, file, page and board with direct rectangle, ellipse and pinned literal-text children. It retains unedited member payloads and unknown package data, returns the original archive byte-for-byte on no-op synchronization, and applies ZIP, expanded-data, member, compression and JSON resource limits before parsing.

The nuif-react-jsx-0 profile extracts one directly returned, marked intrinsic JSX subtree without executing JavaScript. It maps fixed flex containers and literal pinned-font text through byte spans, retains unrelated module source and rejects components, spreads, handlers and runtime expressions.

The nuif-svelte-static-0 profile maps one marked static Svelte component made of regular containers and literal text. It patches the same 21 semantic correspondences through the shared scalar planner, rejects executable template constructs and checks every synchronized source against the exact official Svelte compiler as a foreign oracle.

The nuif-figma-plugin-snapshot-0 profile now implements the credential-free pure mapping between normalized Plugin API objects, canonical NUIF and a host mutation-plan tree. The compiled no-network review shell in figma/plugin consumes that exact schema, requires confirmation before mutation and is checked against the Rust importer. It covers a deliberately narrow visible/opaque fixed-size subset, repairs portable identity deterministically and reports every declared Figma-only property. The shell is static evidence, not a live Figma claim.

The remaining researched or externally bounded targets are Affinity, Canva, Flutter, SwiftUI and Jetpack Compose. Figma and Canva retain bounded API-host draft profiles and a serializable host-object correspondence report; Affinity has a separate user-mediated SVG bridge draft. None has a corresponding live host claim. Broader HTML/CSS, SVG and DTCG profiles remain separate future work beyond the ten executable profiles. Each adapter must emit structured fidelity diagnostics and record provenance/correspondence sufficient for later synchronization and minimal source patches where feasible.

STATUS.md records the current primary integration surface, implementation status, next bounded profile and exclusion boundary for every advertised target. Research coverage and executable conformance are listed separately.

index.json is the machine-readable counterpart. cargo xtask adapter-audit requires all advertised targets to have a primary research record, explicit target and per-profile directionality, a next bounded profile and a non-empty boundary. Integrated entries additionally require each profile’s directions to be a subset of the target union plus crate, profile and routed gate paths; non-integrated entries cannot claim executable directions. The audit writes target/adapter-coverage-report.json and blocks the complete gate.

Vendor-specific semantics belong in namespaced extensions or adapter-local logic; they must not leak into the core merely because a vendor is popular.

Source and file-interchange adapters use AdapterReport and byte-span or artifact correspondence. Plug-in/API hosts use HostAdapterReport and stable host-object identifiers because they do not expose retained source bytes. See ADRs 0008 and 0012 and docs/HOST-INTEGRATION.md.

Canonical source.

NUIF Figma review shell

This directory contains the compiled, no-network host shell for the bounded nuif-figma-plugin-snapshot-0 profile. It is a development and review tool, not a published Figma Community plug-in and not live-host conformance evidence.

The shell intentionally does not contain a made-up plug-in ID. Figma assigns that ID when a reviewer creates a development plug-in. The checked-in manifest is therefore a template and cannot be imported as-is.

Build and review

Requires the pinned Node range in package.json.

npm ci --ignore-scripts --no-audit --no-fund
npm run check

This compiles the main thread against the exact official Figma typings, builds an inline UI, runs the pure protocol/normalizer tests and emits dist/ with a deterministic build report. The manifest declares allowedDomains: ["none"]; the build also rejects remote URLs in generated files.

To create a locally importable manifest, first use Figma’s development plug-in flow to obtain an ID, then run:

FIGMA_PLUGIN_ID=your-assigned-id npm run package

Replace the illustrative value with the exact ID Figma assigned to your development plug-in, then import dist/manifest.json. Do not commit that generated manifest.

Export and import flow

Export requires exactly one selected frame and downloads a normalized snapshot:

nuif import figma-plugin-snapshot-0 selection.figma-snapshot.json selection.nuif.json fidelity.json

Import starts from canonical NUIF and creates a mutation plan outside Figma:

nuif export selection.nuif.json figma-plugin-snapshot-0 plan.json fidelity.json