FacetDocs

Developer commands

These commands measure and debug Facet itself; you do not need them to design. They sit behind one door, facet dev, so facet --help and facet guide list the product only. facet dev --help lists them, and FACET_DEV=1 adds them to facet --help.

Timing the window

facet dev bench --samples 30 --json         # live command-to-recording latency
facet dev smoothness                        # frame rate, dropped frames, input latency, jerk, flicker
facet dev oracle arm                        # capture frames while you use the window
facet dev oracle                            # compare them with references at rest

Recording input

facet dev input record session.jsonl        # every event entering the window
facet dev input stop
facet dev input play session.jsonl --report # replay it, then frame budgets per kind of gesture
facet dev input synth pan -o pan.jsonl      # a session made without a person

Synthetic typing fidelity

facet schema input_contract
facet dev input play keys.jsonl --contract contract.json --report --json

Included in 0.3.133, V1 supports canvas_type only, with the named page already active: a saved clean temporary fixture, generated ids and SHA-1 fixture/recording fingerprints, exact initial text, forward UTF-8 byte caret, canvas focus/view and one expected text/caret checkpoint per printable key. For Note at [2,2], synthetic {"text":"rx","cadence_ms":40} must produce Norte/[3,3] then Norxte/[4,4]. Generate bounds, scale, ids and fingerprints from your own isolated fixture; the repository's exact-caret test creates a complete saved example. Use external temporary storage and a separate CANVAS_HOME/socket; save before opening the host and reopen the saved temporary copy to restore it. Temporary fixtures live under $TMPDIR/<unique fixture>/ (external TMPDIR on this Mac), are created atomically and cleaned only by their owning test. The Home test runs its actual click/key assertions in a bounded copy of its own test executable, with child-only home/temp and parent-sentinel/recents checks; no global environment change or native app launch. No recording is needed or started.

Targets must be uniform, visible/unlocked standalone root text with declared and measured AutoWidth, default TextFlow, no truncation/max_lines, spans, paint/image, exclusions or linked story. Rich runs, wrapping/resized boxes, linked stories and advanced paints fail before setup side effects. Nondefault uniform font/style metadata stays supported and frozen. Contract setup establishes editing; subsequent keys use real focused dispatch. The separate Home-search regression proves a physical search click and keys, not Home-button or file-row routing.

Only file input, loops absent or 1, printable non-held keys/releases, text shorthand, pauses and time markers are accepted; no shortcuts, pointer actions or mutating prefix. Manifest setup overrides legacy header restoration. Every key verifies text/caret and frozen scene/navigation-camera invariants, including node/page order, full target style/spans/node properties, resolved paint and style-library values. Only TextId, content and derived bounds are excluded from target metadata; exact text/caret use checkpoints. A fresh live-window final observation precedes verification and catches state drift after the last key. Normal smoothness JSON includes fidelity; --report --json retains top-level fidelity. Pending is unfinished, invalid carries reasons, and only completed checkpoints can verify. Waiting contracted failures print JSON then exit nonzero; contracted --no-wait is pending. Legacy --no-wait, with or without --report, preserves the complete original JSON reply envelope (outcome, state and extra fields). Legacy runs remain playable and visibly unverified (missing_contract), including old JSON; historical window gates are unchanged. Full Stage 1 chrome/file/page, camera, marquee and 24k contracts remain follow-ups. See repository CLI.md and TESTING.md for the complete manifest and validation protocol.

The PDF engine

facet dev pdf-check notes.md --style s.mdstyle.json   # name each block the direct layout lays out differently
facet dev pdf-blocks notes.md                         # the parsed blocks, as JSON
facet dev pdf-units notes.md --style s.mdstyle.json   # each block's filled node, as JSON

Diagnostic switches

facet dev env prints every diagnostic environment variable, what reads it and its value in your shell: the CANVAS_*_CHECK cross-checks, MDPDF_*, CANVAS_TEXT_DEFER, MEMORY_GUARD, CHECK_TARGETS_CACHE and SCCACHE.

facet dev doctor lists what stopped hosts left behind in ~/.facet/docs (their pid, log and socket files, sockets nothing listens on, registry entries of processes that are gone or whose socket does not answer) with counts and bytes; facet dev doctor --fix removes them, never a live process's, so it is safe while the app is open. Run it when facet files is slow. Hosts remove their own files when they exit cleanly, and facet files prunes dead hosts' leftovers (at most 100 per call), so this is only needed for a large backlog.

The old names (facet smoothness, facet input, facet bench, facet pdf --check) still work in this release, with a note, and go in the next.

Translation history

Fractional multi-root translations retain one move-history entry per batch publication, including when floating-point displacement differs between roots. Scene::moves_since preserves each root's actual world delta and combines contiguous entries newest first. Uniform batches share one delta; other batches retain individual deltas. Roots whose geometry did not change are omitted, including when a tiny residual rounds away at their position. History remains bounded to 512 entries; an expired state or a nontranslation content edit (such as a color change) still returns None, so callers keep their existing full-update fallback. Group refitting and editor batch admission keep their existing geometry behavior.

The portable translate_roots and drag24k_history test targets cover exact displacement bits, history continuity and gesture undo with explicit frame-background selection in the frame-grid gesture fixture. This representation change adds no trace fields or developer flags and makes no measured frame rate claim. See TESTING.md for the warm-validation and mutation protocol.

Optional offline motion evidence

The Python-only scripts/motion_gaps.py --manifest FILE --budgets FILE --out FILE command analyzes byte-hashed raw frame/presentation and explicit-timestamp input fixtures. The old native replay runner, judge and preset budgets were retired on 4 November 2026. An explicit policy is required for standalone accounting; synthetic evidence does not certify live smoothness. See the repository's docs/DEVELOPMENT-PIPELINE.md for the replacement proposal.

Accounting uses all positive presentations, including presentations without canvas paints. Paint gaps, input timestamp gaps and observed presentation intervals stay separate. Each active presentation pair counts once (N−1 for N presentations), including input-starved spans and kind handoffs. Carried canvas state is history, never a newly measured pose. Real applied camera checkpoints prove only the supplied trajectory; canvas-type fidelity proves no pan/pinch contract. Unknown callback coverage cannot prove a physical window freeze.

The proposed 50 ms maximum and 0.5% two-period-gap share limits are provisional; equality passes each limit. Share acceptance requires 200 intervals per required kind and all motion; that is resolution, not statistical power. Strict missing evidence is UNVERIFIED (exit 2), invalid evidence or a supported breach fails (exit 1). Every declared run is checked, including controlled load.

V1 can say only “PASS synthetic accounting; live gate coverage absent.” Legacy phase encoding, nominal maximum Hz and caller-supplied completeness do not certify native phase preservation, measured refresh cadence or drained queues. Live normalized metrics remain unavailable. This branch adds no collector, instrumentation, runtime fix, capture or cause attribution, and does not close the original hitch investigation or the remaining input-state contracts.

Strict motion evidence requires completed replay (playing is integer zero), a known presented initial real camera and a matching fresh final presented actual. Retained initial state is usable only with complete synthetic canvas provenance; unknown history cannot certify motion. Applied-input camera checkpoints alone do not establish the final displayed pose. Pending/missing evidence stays UNVERIFIED; malformed completion, known no-op or contradictory final actual is INVALID. Observed timelines remain available, and the synthetic/live/native limits above continue to apply.

Pure translations can retain linked units through indexed admission and placement slots. Full adoption builds the structural index once; placement keeps it even though canonical linked values are provisional. Changed shape, ordered children, visibility, paint inputs or linear transforms refuse reuse before either moved route. Clipping, partial units, unequal shared runs and plan-space changes keep the general fallback. The consumer also rejects the pre-existing #694 resize-history gap; it does not change that producer.

CANVAS_EDIT_TRACE appends slots, respliced units, journaled status, supplied move count and an optional move diagnostic (route/refusal, eligibility_ms, slot_ms). Eligibility precedes the first mirror write; slot time includes placement and dependency rebound. A missing attempt is None. General and refine initialization includes full topology/pending setup, while slot patches retain those tables. Read-only World work counters distinguish indexed root lookups, page scans, topology setup, moved nodes/child edges, placed ops, dependency edges, full diffs, link/glue visits and pending initialization. The root dependency graph may still read all page inputs; no measured frame rate improvement or fixed latency follows from these counters.

World's hash/map and Coverage choice are shared pure definitions. Metal device code and cache helpers remain platform-gated; default coverage, case-sensitive CANVAS_EXACT_RASTER=msaa selection and hashing are unchanged. The portable drag_work tests and existing macOS pixel checks cover different parts of this contract. See TESTING.md for source-bound warm validation and nine semantic mutations. No developer flag or CLI control was added.

Fractional slot moves recompute derivable unowned aggregate bounds from the already placed children (#696), keeping their exact union aligned across repeated moves and reversals. Recorded blur regions retain the existing shift fallback. Those real dependency reads remain charged; no page cache or O(k) claim is added. The portable aggregate regression and eighth semantic mutation are authored; runtime validation and Linux proof remain pending a lead lease.

Documentation for Facet 0.3.228-g032727de