cjm-substrate-qt-kit

The ONE Qt foundation library for the cjm-substrate application lane (ruling 8b7351e4), in three strata: (a) the design-system runtime — semantic theme tokens as data -> QPalette + QSS + fonts; (b) the app shell (ruling 2bae2cc1, landing); (c) the chrome every app shares — the loop-thread session base, KeymapRegistry, key hints + the modal grammar, the status strip, find bar, picker list, form shell + the manifest-driven config-form model, the HITL panel, the span player (requires ffmpeg on PATH), and text clamps. Born at first duplication between the workbench and the transcription shell (DEC dcf8a712); grown by demand, never speculation. The Textual-era tui-kit's live pieces (ConfigForm, tail) ported here 2026-09-25 and the tui-kit archived — nothing Textual remains on any app's import path.

Modules

• cjm_substrate_qt_kit.__init__ — The ONE Qt foundation library for the cjm-substrate application lane (ruling 8b7351e4).
• cjm_substrate_qt_kit.configform — Manifest-driven config form MODEL — the schema half of every kit form.
• cjm_substrate_qt_kit.findbar — The lane's find-bar universal (the Ctrl-F half of signal c7955f25).
• cjm_substrate_qt_kit.formdialog — Kit FormShell (work item d55292f9): the frameless modal FORM chrome —
• cjm_substrate_qt_kit.hitl — Kit HITL confirm chrome (work item 55bcc3c5, the payload-agnostic half of
• cjm_substrate_qt_kit.keyhints — Keyboard-hints surface: the ?-overlay + contextual hint line (DEC 2a42c028).
• cjm_substrate_qt_kit.keymap — KeymapRegistry: the QAction layer from the toolbox verdict (DEC d55f1d0f).
• cjm_substrate_qt_kit.keys — The keybinding helper both shells grew independently.
• cjm_substrate_qt_kit.layout — Layout roles for the application lane — the FastHTML-era framework's Qt
• cjm_substrate_qt_kit.loopthread — The loop-thread session base: a private asyncio loop behind a Qt shell.
• cjm_substrate_qt_kit.pickerlist — Kit PickerList (work item 8d29f0f0): the native list PAGE the painted
• cjm_substrate_qt_kit.player — Span playback over ONE persistent audio stream — the Qt lane's one audio
• cjm_substrate_qt_kit.statusstrip — StatusStrip: the footer's slot model (DEC 2a42c028).
• cjm_substrate_qt_kit.style — Row-style vocabulary for the lane's list widgets.
• cjm_substrate_qt_kit.testbed — Readability test-bed: error-seeded reading trials measuring which theme
• cjm_substrate_qt_kit.testbed_corpus — Bundled clean-prose corpus for the readability test-bed.
• cjm_substrate_qt_kit.text — Text clamps for one-line surfaces — path-like strings keep their END.
• cjm_substrate_qt_kit.theme — Semantic theme tokens for the lane: one flat dict -> QPalette + QSS + fonts.

API

cjm_substrate_qt_kit.configform

• ConfigField class — One schema property as an editable form row.
• ConfigForm class — A capability's editable config, derived from its manifest config_schema.

cjm_substrate_qt_kit.findbar

• FindBar class — Incremental find over an attached text pane. While the bar is open the

cjm_substrate_qt_kit.formdialog

• FormShell class — Frameless modal shell: head (QTextBrowser, fixed) / body (PickerList,

cjm_substrate_qt_kit.hitl

• HitlPanel class — The composed confirm panel: worklist (stretch) over the verdict strip
• ProposalWorklist class — The proposal list page: items above (a kit PickerList), the host's
• ProvenancePane class — Key/value provenance — a two-column table of whatever the lane's
• VerdictStrip class — The derived-verdict status strip: one line per tier, each verdict
• fmt_ts function — Source-seconds as mm:ss.s — the worklist's span column.
• worklist_row function — Project one item into a picker row: tier glyph (? / ??), the category

cjm_substrate_qt_kit.keyhints

• KeyHintsOverlay class — ?-toggled keyboard-hints overlay. Modal + frameless, centered over
• column_count function — Responsive column count: what the CONTAINER width affords (layout
• group_entries function — [{verb,label,key,group}] -> [(group, entries)] in first-seen group
• hint_line function — Project the pinned verbs (in pin order, capped at limit) into the
• is_close_anchor function — True for the close affordance modal_header paints — the dialog's
• keycaps function — Public key-cap renderer — the overlay's chip grammar for OTHER
• modal_bounds function — (avail_w, avail_h) a kit modal may occupy: the owner's size less a
• modal_header function — A kit modal's title row: the title at left, the mouse CLOSE
• open_centered function — Open a kit modal centered over its owner at (width, height) capped by
• render_hints_html function — The overlay's document: sections distributed across columns in

cjm_substrate_qt_kit.keymap

• KeymapRegistry class — Declarative verb table -> live QActions on an owner widget.

cjm_substrate_qt_kit.keys

• bind function — One QShortcut: key on parent (default: the owner window) fires fn.

cjm_substrate_qt_kit.layout

• afford function — R3 container affordance: how many fixed-width units fit in the
• classify function — One geometry -> its three role ids: {"mode", "shape", "height"}.
• height_tier function — Absolute height -> height-tier role id ("H1".."H4").
• mode function — Width -> mode role id ("M1".."M6").
• shape function — Aspect ratio -> shape role id ("S1".."S6").

cjm_substrate_qt_kit.loopthread

• LoopThreadSession class — Owns one daemon asyncio loop thread; subclasses put their subsystem's

cjm_substrate_qt_kit.pickerlist

• PickerList class — The kit list page: native list above, budget-reserved detail below.
• SpanRowDelegate class — Paint one row's rich-text fragment (the _ROW_HTML data) through a
• spans_to_html function — Project style-worded spans into one QTextDocument-ready fragment.

cjm_substrate_qt_kit.player

• SpanPlayer class — Play/stop one file span at a time over the persistent stream; replay
• decode_command function — The ffmpeg invocation for one span: input-side seek (fast), -t bounds

cjm_substrate_qt_kit.statusstrip

• StatusStrip class — Two-row footer: chips + readout + transient above, hint line below

cjm_substrate_qt_kit.style

• apply_row_style function — Map a row's style words onto a list item (color words + bold).

cjm_substrate_qt_kit.testbed

• ClickPane class — Read-only pane reporting the whitespace-token index of clicks that
• TrialWindow class — The trial loop: render the paragraph under its variant, take the
• build_trials function — The trial plan: variants covered evenly (shuffled round-robin over the
• build_variants function — Cross the sweep dimensions into variant dicts. Defaults reproduce the
• load_paragraphs function — Prose paragraphs from a markdown file: fence markers stripped (fence
• main function — CLI: run trials over a markdown file, or summarize result JSONLs.
• seed_error function — Apply one error class to a token list; (mutated_words, target_token,
• summarize function — Catch rate + latency per dimension marginal, per variant cell, per

cjm_substrate_qt_kit.text

• tail function — Clamp a string to width keeping its END.

cjm_substrate_qt_kit.theme

• apply_theme function — THE entry point: resolve the theme and land palette + QSS + ui font on
• build_palette function — Project the palette roles onto QPalette so NATIVE widgets follow the
• build_qss function — Generate the lane's QSS layer: chrome polish + dynamic-property state
• current_theme function — The theme apply_theme last landed (default-resolved before any apply).
• document_css function — Default stylesheet for rich-text documents (setDefaultStyleSheet):
• load_theme function — Read a theme-as-data JSON file (a flat token dict): themes are shared
• make_font function — Build the theme's font for a slot: "body" / "mono" / "ui". An empty
• resolve_theme function — Merge override tokens onto the built-in pair member for the scheme
• state_color function — Resolve a legacy style word or a semantic role to the theme's color
• style_text_pane function — Reading-quality setup for a text pane (QTextEdit / QTextBrowser /

Dependencies

Depends on: PySide6 Used by: cjm-graph-workbench-qt, cjm-session-scratchpad-qt, cjm-transcript-correction-qt, cjm-transcript-decomp-qt, cjm-transcription-qt, cjm-workflow-hub-qt