@quillmark/svelte 0.23.0 → 0.24.0

package/README.md

@@ -14,12 +14,12 @@ npm install @quillmark/svelte
 
 Each subpath is its own module root; a bundler pulls only what the entry you import reaches.
 
-| Import                      | Surface                                                                                                               |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `@quillmark/svelte/core`    | What the surfaces share: the `DocPath`/`Place` address vocabulary, the `EditorError` channel, `init`. Framework-free. |
-| `@quillmark/svelte/preview` | The live preview: `createPreview` + `<Preview>`. Reaches nothing editor-side.                                         |
-| `@quillmark/svelte/visual`  | The federated WYSIWYG: `<VisualEditor>`, the codec's `createField` prose leaf.                                        |
-| `@quillmark/svelte`         | Re-exports `/core`.                                                                                                   |
+| Import                      | Surface                                                                                                                |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `@quillmark/svelte/core`    | What the surfaces share: the `DocPath`/`Place` address vocabulary, the `EditorError` channel, `init`. No UI framework. |
+| `@quillmark/svelte/preview` | The live preview: `createPreview` + `<Preview>`. Reaches nothing editor-side.                                          |
+| `@quillmark/svelte/visual`  | The federated WYSIWYG: `<VisualEditor>`, the codec's `createField` prose leaf.                                         |
+| `@quillmark/svelte`         | Re-exports `/core`.                                                                                                    |
 
 ## Open a session
 
@@ -29,8 +29,7 @@ The **consumer** owns the session and the handles, and drives every edit; the su
 import { Engine } from '@quillmark/wasm';
 import { init } from '@quillmark/svelte/core';
 
-// One-time, and the only door to Quill and Document: the artifact exports
-// neither statically.
+// Quill and Document are exported only through init(), which loads the wasm once.
 const { Quill, Document } = await init();
 
 const quill = Quill.fromTree(tree); // tree: Map<string, Uint8Array> of the quill dir

package/dist/core/codec/decode.d.ts

@@ -29,7 +29,8 @@ export declare function fitsInline(rt: Content): boolean;
 export declare function fitsPlain(rt: Content): boolean;
 /** Whether a leaf so declared edits `rt` losing nothing: {@link fitsInline} narrowed
  *  and {@link fitsPlain} plain, past which the decode drops what the first commit would
- *  store; on the block schema anything but an element ({@link editable}),
+ *  store; on the block schema anything but a construct read and not edited — an element,
+ *  a definition list ({@link editable}), a footnote or an equation (`isEditedIsland`) —
  *  and an island where the leaf mounts no island view (`islands`), which draws as its
  *  placeholder tag, an atom a keystroke deletes unseen. What a leaf held over the rest
  *  reads. */

package/dist/core/codec/decode.js

@@ -8,7 +8,7 @@
 // applied here; they are decorations (field.ts). Positions throughout are USV; `Array.from` iterates by
 // code point so an astral char is one unit, never a surrogate half.
 import { DOMSerializer } from 'prosemirror-model';
-import { ISLAND_SLOT, isBlockIsland } from './islands.js';
+import { ISLAND_SLOT, isBlockIsland, isEditedIsland } from './islands.js';
 import { descriptorOf, markKey, pmMarkFromContent } from './marks.js';
 import { core } from '../lifecycle.js';
 import { hasMarks, isBlockSchema, isInlineSchema, takesLineBreak } from './schema.js';
@@ -96,7 +96,8 @@ export function fitsPlain(rt) {
 }
 /** Whether a leaf so declared edits `rt` losing nothing: {@link fitsInline} narrowed
  *  and {@link fitsPlain} plain, past which the decode drops what the first commit would
- *  store; on the block schema anything but an element ({@link editable}),
+ *  store; on the block schema anything but a construct read and not edited — an element,
+ *  a definition list ({@link editable}), a footnote or an equation (`isEditedIsland`) —
  *  and an island where the leaf mounts no island view (`islands`), which draws as its
  *  placeholder tag, an atom a keystroke deletes unseen. What a leaf held over the rest
  *  reads. */
@@ -105,11 +106,16 @@ export function fitsLeaf(rt, leaf) {
         return fitsInline(rt);
     if (leaf.plaintext)
         return fitsPlain(rt);
-    return (leaf.islands || rt.islands.length === 0) && rt.lines.every(editable);
+    if (!leaf.islands && rt.islands.length)
+        return false;
+    return rt.islands.every((isl) => isEditedIsland(isl.type)) && rt.lines.every(editable);
 }
-/** Whether every container on `line` is one the block schema edits: an element decodes
- *  to no node, so the first commit would drop it. */
+/** Whether the block schema edits `line`'s kind and every container on it: a term draws
+ *  as a paragraph and an element and a description as the blocks they wrap, so the first
+ *  commit would drop each. */
 function editable(line) {
+    if (line.kind === 'term')
+        return false;
     return line.containers.every((c) => c.container === 'quote' || c.container === 'list_item');
 }
 /** Inline decode: one paragraph, containers and islands stripped. */
@@ -192,9 +198,9 @@ function groupBlocks(schema, leaves, depth, marks, cursor) {
             i = j;
             continue;
         }
-        if (here.container === 'element') {
-            // No node holds an element, and a leaf holding one is held (`fitsLeaf`), so
-            // what it wraps draws in place, read-only.
+        if (here.container === 'element' || here.container === 'description') {
+            // No node holds an element or a description, and a leaf holding one is held
+            // (`fitsLeaf`), so what it wraps draws in place, read-only.
             const key = containerKey(here);
             let j = i + 1;
             while (j < leaves.length) {
@@ -249,7 +255,7 @@ function instanceOf(c) {
 }
 /** Identity of a container for run gathering: its name, its `instance` and an element's
  * attributes, NUL-joined as `markKey` joins a mark's. `list_item` carries its own run
- * rule, so the quote and the element are what key here. */
+ * rule, so the rest are what key here. */
 function containerKey(c) {
     const attrs = c.container === 'element' ? JSON.stringify(c.attrs) : '';
     return `${c.container}\u0000${instanceOf(c)}\u0000${attrs}`;
@@ -269,13 +275,15 @@ function makeLeaf(schema, leaf, marks, cursor) {
             return schema.nodes.code_block.create({ lang: line.attrs?.lang ?? null }, content);
         }
         case 'para':
+        case 'term':
         case 'heading': {
-            if (line.kind === 'para' && blockIslandLine(leaf, cursor))
+            if (line.kind !== 'heading' && blockIslandLine(leaf, cursor))
                 return schema.nodes.island_block.create(islandAttrs(cursor));
             // Inline content, the segment boundary a `hard_break` in a paragraph and a space
             // in a heading, which takes none (`schema.ts` §`takesLineBreak`). A stored heading
             // carries no continuation — the store clears one after a block of a single line —
-            // so the space is what keeps a hand-built content decodable.
+            // so the space is what keeps a hand-built content decodable. A term draws as a
+            // paragraph, read-only (`fitsLeaf`).
             const type = line.kind === 'heading' ? schema.nodes.heading : schema.nodes.paragraph;
             const inline = [];
             leaf.segments.forEach((seg, idx) => {

package/dist/core/codec/field.d.ts

@@ -28,7 +28,8 @@ export interface CreateFieldOpts {
      * leaf, or a `text` one, is held over a value its schema cannot
      * hold (`fitsLeaf`, upstream's `isInline` and `isPlain`): the decode would join lines
      * and drop containers and islands for the first commit to store. Any leaf is held
-     * over an element, which no node holds. A held leaf draws
+     * over what is read and not edited: an element, a definition list, a footnote and an
+     * equation (CODEC §Decode). A held leaf draws
      * its content on the block schema, read-only, and commits nothing. Judged of the value
      * each mount and re-hydrate reads, so {@link FieldController.applyExternal} is what
      * re-evaluates it.

package/dist/core/codec/islands.d.ts

@@ -5,9 +5,12 @@ import type { ContentIsland, TableProps } from '@quillmark/wasm';
 export declare const ISLAND_SLOT = "\uFFFC";
 /** Whether an island of `type` is block markup: a `table` stands alone on its line. */
 export declare function isBlockIsland(type: ContentIsland['type']): boolean;
+/** Whether a leaf edits an island of `type`; one holding any other is held (`fitsLeaf`). */
+export declare function isEditedIsland(type: ContentIsland['type']): boolean;
 /** Block island node (a table): a `U+FFFC` slot alone on its `para` line. Atom, unselectable content. */
 export declare const islandBlockSpec: NodeSpec;
-/** Inline island node (an image): a `U+FFFC` slot inside a `para` line. */
+/** Inline island node (an image, a footnote, an equation): a `U+FFFC` slot inside a
+ *  `para` line. */
 export declare const islandInlineSpec: NodeSpec;
 /** A PM island node's attributes: the content entry, spelled the way a node spec
  *  spells it (`islandType`, because `type` on a PM node is the node type). `islandType`

package/dist/core/codec/islands.js

@@ -1,10 +1,11 @@
 // Islands: the `U+FFFC` slot + `ContentIsland` entry ↔ a PM leaf node. Every slot sits
 // in a `para` line; the island's type says which node it is, a `table` a block alone on
-// its line and an `image` inline. The node carries `id`, `islandType` and `props` verbatim.
+// its line and every other type inline. The node carries `id`, `islandType` and `props`
+// verbatim.
 //
 // A props-aware consumer reads the shape straight off the boundary:
-// `ContentIsland.props` is the typed union (`TableProps` for `table`,
-// `ImageProps` for `image`; DOCUMENT_MODEL §Stability seams), so the codec
+// `ContentIsland.props` is the typed union (`TableProps` for `table`, `ImageProps` for
+// `image`, …; DOCUMENT_MODEL §Stability seams), so the codec
 // reads it rather than hand-rolling a shape. `type` is a closed set, so a
 // discriminant check narrows it; `props` still crosses the DOM as opaque JSON,
 // which is what §`tablePropsOfNode` guards.
@@ -38,25 +39,35 @@ function islandDOM(node) {
     };
 }
 /** The island types the content model names, each with whether its markup is a block,
- *  which decides the node its slot decodes to. A `Record` over the boundary's own union,
- *  so a member added upstream is a missing key here rather than a silent refusal at the
- *  one door with no decode behind it. */
-const BLOCK_ISLAND = { table: true, image: false };
+ *  which decides the node its slot decodes to, and whether a leaf edits it. A `Record`
+ *  over the boundary's own union, so a member added upstream is a missing key here
+ *  rather than a silent refusal at the one door with no decode behind it. A footnote and
+ *  an equation are read, not edited (CODEC §Decode): a leaf holding one is held. */
+const ISLANDS = {
+    table: { block: true, edited: true },
+    image: { block: false, edited: true },
+    footnote: { block: false, edited: false },
+    math: { block: false, edited: false }
+};
 /** Whether an island of `type` is block markup: a `table` stands alone on its line. */
 export function isBlockIsland(type) {
-    return BLOCK_ISLAND[type];
+    return ISLANDS[type].block;
+}
+/** Whether a leaf edits an island of `type`; one holding any other is held (`fitsLeaf`). */
+export function isEditedIsland(type) {
+    return ISLANDS[type].edited;
 }
 /** An island node's attributes off that DOM, or `false` where the id is absent or the
- *  type is one the content vocabulary does not name — a name no read produces and no
- *  write takes, so the element's text arrives as text. A `props` that is not the JSON
- *  written above reads as `null`, and one of the wrong shape is `undefined` at its
- *  reader (§`tablePropsOfNode`): the entry survives as an island of its type rather
- *  than taking the paste down with it. */
+ *  type is one no leaf edits — a name the vocabulary does not hold, or a footnote or an
+ *  equation, which no gesture mints — so the element's text arrives as text. A `props`
+ *  that is not the JSON written above reads as `null`, and one of the wrong shape is
+ *  `undefined` at its reader (§`tablePropsOfNode`): the entry survives as an island of
+ *  its type rather than taking the paste down with it. */
 function islandAttrsFromDOM(el) {
     const id = el.getAttribute('data-qm-island-id');
     // Asserted off an untrusted attribute and checked against the set on the next line.
     const type = el.getAttribute('data-qm-island');
-    if (id == null || type == null || !Object.hasOwn(BLOCK_ISLAND, type))
+    if (id == null || type == null || !Object.hasOwn(ISLANDS, type) || !isEditedIsland(type))
         return false;
     const raw = el.getAttribute('data-qm-island-props');
     let props = null;
@@ -86,7 +97,8 @@ export const islandBlockSpec = {
     parseDOM: [{ tag: 'div[data-qm-island]', getAttrs: (el) => islandAttrsFromDOM(el) }],
     toDOM: (node) => ['div', islandDOM(node), `[${node.attrs.islandType || 'island'}]`]
 };
-/** Inline island node (an image): a `U+FFFC` slot inside a `para` line. */
+/** Inline island node (an image, a footnote, an equation): a `U+FFFC` slot inside a
+ *  `para` line. */
 export const islandInlineSpec = {
     group: 'inline',
     inline: true,
@@ -94,8 +106,23 @@ export const islandInlineSpec = {
     selectable: true,
     attrs: islandAttrs,
     parseDOM: [{ tag: 'span[data-qm-island]', getAttrs: (el) => islandAttrsFromDOM(el) }],
-    toDOM: (node) => ['span', islandDOM(node), `[${node.attrs.islandType || 'island'}]`]
+    toDOM: inlineIslandDOM
 };
+/** An inline island's DOM: a footnote its reference mark, whose number `prose.css` draws
+ *  in reading order and whose note is its title, an equation its TeX between the dollars
+ *  that write it, and an image its tag. */
+function inlineIslandDOM(node) {
+    const attrs = node.attrs;
+    const dom = islandDOM(node);
+    const props = attrs.props;
+    if (attrs.islandType === 'footnote')
+        return ['sup', typeof props?.text === 'string' ? { ...dom, title: props.text } : dom];
+    if (attrs.islandType === 'math' && typeof props?.tex === 'string') {
+        const fence = props.display ? '$$' : '$';
+        return ['span', dom, `${fence}${props.tex}${fence}`];
+    }
+    return ['span', dom, `[${attrs.islandType || 'island'}]`];
+}
 /** Build a content island entry from a PM island node's attrs (block or inline). The
  *  cast pairs a closed `type` with a `props` that crossed the DOM as opaque JSON. The
  *  store is lenient about a table's shape — it fills what it can and keeps the rest —

package/dist/core/codec/markdown-paste.d.ts

@@ -2,8 +2,9 @@ import { Plugin } from 'prosemirror-state';
 /**
  * A block leaf's markdown paste, consulted after the table paste: ProseMirror hands text
  * over only where the clipboard holds no HTML, whose DOM parse reads the source's own
- * structure, so HTML wins. A paste as plain text keeps the text. An island the parse
- * builds arrives under the id `importMarkdown` minted, which the paste's island pass
- * re-mints where the field holds it (`islands.ts`).
+ * structure, so HTML wins. A paste as plain text keeps the text, and so does a parse
+ * building a construct no leaf edits (`fitsLeaf`). An island the parse builds arrives
+ * under the id `importMarkdown` minted, which the paste's island pass re-mints where the
+ * field holds it (`islands.ts`).
  */
 export declare function markdownPastePlugin(): Plugin;

package/dist/core/codec/markdown-paste.js

@@ -7,7 +7,7 @@
 import { Slice } from 'prosemirror-model';
 import { Plugin } from 'prosemirror-state';
 import { core } from '../lifecycle.js';
-import { decode } from './decode.js';
+import { decode, fitsLeaf } from './decode.js';
 import { blockSchema } from './schema.js';
 /** A line opening a block markdown spells and prose does not: a bullet or an ordered item at
  *  any indent, and within CommonMark's three spaces an ATX heading, a quote, a fence, or a
@@ -21,9 +21,10 @@ const BLOCK_HEAD = new RegExp([
 /**
  * A block leaf's markdown paste, consulted after the table paste: ProseMirror hands text
  * over only where the clipboard holds no HTML, whose DOM parse reads the source's own
- * structure, so HTML wins. A paste as plain text keeps the text. An island the parse
- * builds arrives under the id `importMarkdown` minted, which the paste's island pass
- * re-mints where the field holds it (`islands.ts`).
+ * structure, so HTML wins. A paste as plain text keeps the text, and so does a parse
+ * building a construct no leaf edits (`fitsLeaf`). An island the parse builds arrives
+ * under the id `importMarkdown` minted, which the paste's island pass re-mints where the
+ * field holds it (`islands.ts`).
  */
 export function markdownPastePlugin() {
     return new Plugin({
@@ -42,6 +43,8 @@ export function markdownPastePlugin() {
                     // Nesting past the store's depth is refused; the literal text holds it.
                     return null;
                 }
+                if (!fitsLeaf(rt, { inline: false, plaintext: false, islands: true }))
+                    return null;
                 return new Slice(decode(rt, blockSchema).content, 0, 0);
             })
         }

package/dist/core/codec/prose.css

@@ -162,6 +162,21 @@ li.ProseMirror-selectednode::after {
 	pointer-events: none;
 }
 
+/* A footnote and an equation are read, not edited (CODEC §Decode), and draw as what
+   their markdown writes: a footnote its reference mark, numbered in reading order off a
+   counter each leaf resets, its note the marker's title (`islands.ts`); an equation its
+   TeX between its dollars, in the code face. */
+.ProseMirror {
+	counter-reset: qm-footnote;
+}
+.ProseMirror sup[data-qm-island='footnote']::after {
+	counter-increment: qm-footnote;
+	content: counter(qm-footnote);
+}
+.ProseMirror [data-qm-island='math'] {
+	font-family: var(--_qm-font-mono);
+}
+
 /* A link takes the surface's ink (the UA's blue is the `#8cf` defect again) and a
    dotted underline. Dotted rather than solid because `underline` is a mark in the
    same schema, and a solid rule renders an authored `<u>` and a link identically in a

package/dist/index.js

@@ -1,4 +1,4 @@
-// `@quillmark/svelte` root: the framework-free substrate.
+// `@quillmark/svelte` root: the substrate, free of any UI framework.
 //
 // The headline surfaces mount from their own subpaths (`@quillmark/svelte/preview`,
 // `/visual`) so a bundler pulls only what an entry reaches; the root

package/dist/visual/Card.svelte

@@ -1,5 +1,6 @@
 <!--
- One card block, its fields grouped by `ui.group`/`ui.compact`. `main` is headerless
+ One card block, its top-level objects (or legacy `ui.group`s) drawn as panels and its
+ fields packed by `ui.compact`. `main` is headerless
  and takes no controls. Every prose leaf takes a parent-built live address, so a card
  reorder re-targets its commits without a remount.
 -->
@@ -273,9 +274,9 @@
 								{@const headIds = section.head ? ops.domIds(section.head.name) : undefined}
 								{@const headHint = section.head?.description}
 								<div class={['qm-group', { 'qm-open': isOpen }]}>
-									<!-- A flat field alone in its section is named by the header, which
-								     takes its label id and parks its description: the field draws no
-								     label of its own to say the section's name twice. -->
+									<!-- A panel's object, or an object alone in its section, is named by the
+								     header, which takes its label id and parks its description: the field
+								     draws no label of its own to say the section's name twice. -->
 									<div class="qm-group-head">
 										<button
 											type="button"

package/dist/visual/Field.svelte

@@ -33,7 +33,6 @@
 		VARIANT_DISCRIMINANT,
 		arrayLayout,
 		baseType,
-		flatObject,
 		ghostDefault,
 		isContainer,
 		optionalCell,
@@ -174,7 +173,8 @@
 	);
 	// Two controls own their label row, the add chip and the held count sharing it.
 	const ownsLabel = $derived(field.control === 'array' || field.control === 'matrix');
-	const flat = $derived(flatObject(field.schema));
+	// A headed object is a panel's, and the panel is its frame.
+	const flat = $derived(headed);
 
 	// A container walks its diagnostics down to the cell each names and draws the rest
 	// at its own foot (`diagnostics.ts`); every other control draws them here, under

package/dist/visual/ObjectField.svelte

@@ -30,9 +30,8 @@
  member's id. So a cell reads at whatever depth it sits, which nothing here knows.
 
  `bare` is the table's row: the same cells with no labels and no figure of their own,
- laid onto the tracks the table's header names ({@link ArrayField}). `flat` is
- `ui.layout: flat`: the cells keep their labels and lose the figure, standing at the
- depth of whatever holds the subform.
+ laid onto the tracks the table's header names ({@link ArrayField}). `flat` is a
+ panel's object: the cells keep their labels and lose the figure, the panel being it.
 -->
 <script lang="ts">
 	import type { Content, PathStep, QuillFieldSchema } from '@quillmark/wasm';
@@ -42,7 +41,6 @@
 		controlKind,
 		declaredContent,
 		fieldModels,
-		flatObject,
 		humanize,
 		isContainer,
 		literalText,
@@ -103,8 +101,8 @@
 		/** A table's row: the cells alone, on the tracks the table's header names, with
 		 * no labels and no vertical of their own. */
 		bare?: boolean;
-		/** `ui.layout: flat`: no vertical and no rung, the properties at the depth of the
-		 * list the subform stands in. */
+		/** A panel's object: no vertical and no rung, the properties at the depth of the
+		 * panel's field list. */
 		flat?: boolean;
 		/** A card-level object, or one nested in it: its properties are placed as a
 		 * card's fields are (`placeFields`), so moving a field into a group leaves its row
@@ -426,7 +424,6 @@
 						bind:this={nestedEls[key]}
 						value={obj[key] as Record<string, unknown> | undefined}
 						properties={sub.properties}
-						flat={flatObject(sub)}
 						{placed}
 						label={ids ? undefined : fallbackName(key, sub)}
 						idBase={ids?.control}

package/dist/visual/ObjectField.svelte.d.ts

@@ -32,8 +32,8 @@ interface Props {
     /** A table's row: the cells alone, on the tracks the table's header names, with
      * no labels and no vertical of their own. */
     bare?: boolean;
-    /** `ui.layout: flat`: no vertical and no rung, the properties at the depth of the
-     * list the subform stands in. */
+    /** A panel's object: no vertical and no rung, the properties at the depth of the
+     * panel's field list. */
     flat?: boolean;
     /** A card-level object, or one nested in it: its properties are placed as a
      * card's fields are (`placeFields`), so moving a field into a group leaves its row

package/dist/visual/VisualEditorInner.svelte

@@ -54,10 +54,7 @@
 		isContainer,
 		shortCell,
 		schemaAt,
-		fieldModels,
-		groupOrder,
-		groupSections,
-		groupLabel,
+		cardSections,
 		cardTitle,
 		kindTitle,
 		fieldValues,
@@ -325,9 +322,9 @@
 		try {
 			if (value === undefined) {
 				// The unset rung (VISUAL_EDITOR §"The commitment ladder"): removing the field
-				// leaves the engine's authored › `default:` › blank-fill resolve to render the
+				// leaves Quillmark's authored › `default:` › blank-fill resolve to render the
 				// default, where writing one bakes a snapshot the schema cannot track (canon
-				// SCHEMAS.md: the engine never writes a default; the editor writes one only
+				// SCHEMAS.md: Quillmark never writes a default; the editor writes one only
 				// as the edit that takes it). Removal writes no value, so there is
 				// nothing for a schema to conform and the lane is the quill-free one.
 				if (isMain) {
@@ -632,14 +629,11 @@
 			payloadItems: readonly PayloadItem[];
 			ext?: Record<string, unknown>;
 		},
-		cardSchema: Parameters<typeof fieldModels>[0] | undefined,
+		cardSchema: Parameters<typeof cardSections>[0] | undefined,
 		rows: ResolvedCardRows
 	): CardModel {
 		const values = fieldValues(card.payloadItems);
-		const fields = cardSchema ? fieldModels(cardSchema) : [];
-		const sections = cardSchema
-			? groupSections(fields, groupOrder(cardSchema), (g) => groupLabel(cardSchema, g))
-			: [];
+		const sections = cardSchema ? cardSections(cardSchema) : [];
 		const extEditor = card.ext?.editor as { title?: string } | undefined;
 		const hasBody = bodyEnabled(cardSchema);
 		return {

package/dist/visual/strings.d.ts

@@ -122,7 +122,7 @@ export interface VisualStrings extends TableChromeStrings, SlashStrings {
  *
  * - **`validation::enum_violation`, `type_mismatch`, `format_violation`**: the
  *   constraint re-words from the quill's schema at `path`, the offending value from
- *   `args` (`value` / `sourceToken` / `actual`, the engine testifying to what it
+ *   `args` (`value` / `sourceToken` / `actual`, Quillmark testifying to what it
  *   saw) and never from the document at `path`: validation runs post-coercion, so
  *   the validator read a value the document does not hold and a sentence built from
  *   `path` names a spelling the user never typed.
@@ -130,7 +130,7 @@ export interface VisualStrings extends TableChromeStrings, SlashStrings {
  *   refused value being in neither document (unchanged on throw) nor schema.
  * - **`parse::yaml_error_with_location`, `invalid_structure`**: does not re-word. No
  *   `path`; `args` names the block (`blockIndex`) and `location` places the failure in
- *   the document's own coordinates, engine prose riding under no key: the parser's own
+ *   the document's own coordinates, Quillmark prose riding under no key: the parser's own
  *   text, its column and its caret snippet exist only inside `message`.
  * - **`LiveSession.warnings`**: does not re-word. Backend text, an external feed.
  *

package/dist/visual/structure.d.ts

@@ -26,18 +26,17 @@ export interface FieldModel {
     inline: boolean;
     plaintext: boolean;
 }
-/** A `ui.group` section: its label and the fields (declaration order) inside it. */
+/** A panel section, a top-level `object`'s or a legacy `ui.group`'s: its label and the
+ *  fields (declaration order) inside it. */
 export interface GroupSection {
     group: string | undefined;
     label: string;
     fields: FieldModel[];
-    /** The field the section's header names in place of a label of its own: the one
-     * field of a group section, where that field is {@link flatObject}. */
+    /** The object the section's header names in place of a label of its own: the
+     * object a panel is, or a group section's one field where that field is an
+     * `object`. Its properties draw flat, the panel being their frame. */
     head?: FieldModel;
 }
-/** `ui.layout: flat` on a typed dictionary: no frame of its own, its properties
- *  standing at the depth of the fields around it rather than a rung in. */
-export declare function flatObject(schema: QuillFieldSchema): boolean;
 /**
  * One card instance projected for rendering: the schema × payload join result
  * the VisualEditor's `$derived` produces and hands to `<Card>`. Positional
@@ -112,7 +111,7 @@ export declare function resolvedByCardIndex(resolved: Resolved | undefined): Map
 export declare function ghostDefault(row: ResolvedField | undefined): unknown;
 /** A stored `boolean` cell as the render reads it: a boolean, `true` or `false` in any
  * case, or a number by whether it is non-zero; undefined where the render refuses the
- * value. The engine's coercion, restated, so the suite holds it to `reader.resolve()`. */
+ * value. Quillmark's coercion, restated, so the suite holds it to `reader.resolve()`. */
 export declare function renderedBoolean(value: unknown): boolean | undefined;
 /** A ghost value's string form, or undefined for null/object (only text ghosts
  * render a placeholder). A scalar's resolved default reads through it; a content
@@ -207,9 +206,9 @@ export declare function matrixMembers(roster: Record<string, string> | undefined
 export declare function memberValue(map: Record<string, unknown> | undefined, id: string): unknown;
 /**
  * Whether a stored member is held: by being present. A mapping is held whatever it
- * carries, `{}` included, and a bare scalar is the tick itself, read as the engine's
+ * carries, `{}` included, and a bare scalar is the tick itself, read as Quillmark's
  * coercion reads it: `false`, `0`, `"false"` and `null` unheld, every other present
- * scalar held, so a spelling the engine would refuse still draws the tick it claims.
+ * scalar held, so a spelling Quillmark would refuse still draws the tick it claims.
  */
 export declare function matrixHeld(stored: unknown): boolean;
 /** A member's columns: its mapping without the reserved keys, `{}` for a bare tick or an
@@ -245,7 +244,7 @@ export declare function matrixDeclares(matrix: QuillFieldSchema, id: string): bo
 /**
  * The added items a stored map holds, sorted by id as the plate orders them: on an
  * open matrix, each key off the roster spelled as an id whose mapping carries a
- * `title`. Any other key off the roster is the engine's refusal, drawn nowhere and
+ * `title`. Any other key off the roster is Quillmark's refusal, drawn nowhere and
  * ridden through.
  */
 export declare function addedItems(matrix: QuillFieldSchema, map: Record<string, unknown> | undefined): MatrixMember[];
@@ -329,6 +328,19 @@ export declare function groupLabel(cardSchema: QuillCardSchema, group: string):
  * the card schema, which falls back to {@link humanize} itself.
  */
 export declare function groupSections(fields: FieldModel[], order: string[], labelFor: (group: string) => string): GroupSection[];
+/**
+ * Object-panel sections (VISUAL_EDITOR §"Structure mirrors the schema"): every
+ * top-level `object` is a panel of its own, headed by the object, in declaration
+ * order; everything else stands in one unframed section above them. The section id
+ * is the field name, which a card's keys hold unique.
+ */
+export declare function objectSections(fields: FieldModel[]): GroupSection[];
+/**
+ * A card's sections: its ungrouped fields' {@link objectSections}, then each legacy
+ * `ui.group` a panel in registry order, the order the loader settles the fields in.
+ * A panel named as a group is keyed off the group's id space, which `.` never joins.
+ */
+export declare function cardSections(cardSchema: QuillCardSchema): GroupSection[];
 /**
  * The group section a card's accordion opens on first mount: the first in
  * order, or `null` when the card declares none. Ungrouped fields render outside

package/dist/visual/structure.js

@@ -11,11 +11,6 @@ import { core } from '../core/lifecycle.js';
 export function isContainer(kind) {
     return kind === 'array' || kind === 'object' || kind === 'variant' || kind === 'matrix';
 }
-/** `ui.layout: flat` on a typed dictionary: no frame of its own, its properties
- *  standing at the depth of the fields around it rather than a rung in. */
-export function flatObject(schema) {
-    return controlKind(schema) === 'object' && schema.ui?.layout === 'flat';
-}
 /**
  * A card's resolved rows keyed by field name: the provenance channel parallel to
  * {@link CardModel.values}. `resolve` returns rows in declaration order; the
@@ -47,7 +42,7 @@ export function ghostDefault(row) {
 }
 /** A stored `boolean` cell as the render reads it: a boolean, `true` or `false` in any
  * case, or a number by whether it is non-zero; undefined where the render refuses the
- * value. The engine's coercion, restated, so the suite holds it to `reader.resolve()`. */
+ * value. Quillmark's coercion, restated, so the suite holds it to `reader.resolve()`. */
 export function renderedBoolean(value) {
     if (typeof value === 'boolean')
         return value;
@@ -197,16 +192,16 @@ export function memberValue(map, id) {
 }
 /**
  * Whether a stored member is held: by being present. A mapping is held whatever it
- * carries, `{}` included, and a bare scalar is the tick itself, read as the engine's
+ * carries, `{}` included, and a bare scalar is the tick itself, read as Quillmark's
  * coercion reads it: `false`, `0`, `"false"` and `null` unheld, every other present
- * scalar held, so a spelling the engine would refuse still draws the tick it claims.
+ * scalar held, so a spelling Quillmark would refuse still draws the tick it claims.
  */
 export function matrixHeld(stored) {
     if (typeof stored === 'object' && stored !== null)
         return true;
     return tickOf(stored);
 }
-/** A tick's scalar reading: absent and the engine's false spellings unheld, the rest held. */
+/** A tick's scalar reading: absent and Quillmark's false spellings unheld, the rest held. */
 function tickOf(v) {
     if (v === undefined || v === null)
         return false;
@@ -280,7 +275,7 @@ export function matrixDeclares(matrix, id) {
 /**
  * The added items a stored map holds, sorted by id as the plate orders them: on an
  * open matrix, each key off the roster spelled as an id whose mapping carries a
- * `title`. Any other key off the roster is the engine's refusal, drawn nowhere and
+ * `title`. Any other key off the roster is Quillmark's refusal, drawn nowhere and
  * ridden through.
  */
 export function addedItems(matrix, map) {
@@ -526,7 +521,7 @@ export function groupSections(fields, order, labelFor) {
     for (const g of order) {
         const fs = fields.filter((f) => f.group === g);
         if (fs.length) {
-            const head = fs.length === 1 && flatObject(fs[0].schema) ? fs[0] : undefined;
+            const head = fs.length === 1 && fs[0].control === 'object' ? fs[0] : undefined;
             sections.push({ group: g, label: labelFor(g), fields: fs, head });
             emitted.add(g);
         }
@@ -543,6 +538,35 @@ export function groupSections(fields, order, labelFor) {
     }
     return sections;
 }
+/**
+ * Object-panel sections (VISUAL_EDITOR §"Structure mirrors the schema"): every
+ * top-level `object` is a panel of its own, headed by the object, in declaration
+ * order; everything else stands in one unframed section above them. The section id
+ * is the field name, which a card's keys hold unique.
+ */
+export function objectSections(fields) {
+    const panel = (f) => f.control === 'object';
+    const loose = fields.filter((f) => !panel(f));
+    const sections = loose.length
+        ? [{ group: undefined, label: '', fields: loose }]
+        : [];
+    for (const f of fields)
+        if (panel(f))
+            sections.push({ group: f.name, label: f.label, fields: [f], head: f });
+    return sections;
+}
+/**
+ * A card's sections: its ungrouped fields' {@link objectSections}, then each legacy
+ * `ui.group` a panel in registry order, the order the loader settles the fields in.
+ * A panel named as a group is keyed off the group's id space, which `.` never joins.
+ */
+export function cardSections(cardSchema) {
+    const fields = fieldModels(cardSchema);
+    const order = groupOrder(cardSchema);
+    const panels = objectSections(fields.filter((f) => f.group === undefined)).map((s) => s.head && order.includes(s.head.name) ? { ...s, group: `${s.head.name}.` } : s);
+    const grouped = fields.filter((f) => f.group !== undefined);
+    return [...panels, ...groupSections(grouped, order, (g) => groupLabel(cardSchema, g))];
+}
 /**
  * The group section a card's accordion opens on first mount: the first in
  * order, or `null` when the card declares none. Ungrouped fields render outside

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/svelte",
-	"version": "0.23.0",
+	"version": "0.24.0",
 	"description": "Editor, live-preview and source surfaces over a Quillmark WASM session.",
 	"repository": {
 		"type": "git",
@@ -69,7 +69,7 @@
 		"check": "svelte-check --tsconfig ./tsconfig.json --fail-on-warnings"
 	},
 	"peerDependencies": {
-		"@quillmark/wasm": ">=0.126.0-0",
+		"@quillmark/wasm": ">=0.129.0-0",
 		"svelte": "^5.33.0"
 	},
 	"dependencies": {