@markii/stdlib 0.12.1 → 0.14.0

package/dist/editor/fences/container-fences.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Fence auto-extension on insert (editor quality of life, format
+ * untouched): the pure logic behind "the outer fence pair grows when a
+ * container is inserted inside another container".
+ *
+ * docs/format.md gives container directives a fence rule borrowed from
+ * fenced code: nesting works only when the OUTER pair carries more colons
+ * than the inner one, e.g. `::::center` around `:::narrow`. Written by
+ * hand that is a chore, and getting it wrong renders the note wrong. Both
+ * hosts therefore lengthen the enclosing fences for the author, in exactly
+ * two places: the Insert Component command, and accepting a container
+ * component from the completion popup. Never while typing.
+ *
+ * The posture here is conservative on purpose. This module rewrites text
+ * the author did not ask it to touch, so it only ever acts on a document
+ * whose container fences pair cleanly from the top of the file: every
+ * opener strictly longer than the opener it nests inside, every closer
+ * matching its opener's colon count exactly, nothing left dangling at the
+ * end. Anything else, including an unterminated code fence, returns "do
+ * not touch" and the insertion proceeds exactly as it would have before.
+ * A missed extension is a small annoyance; a wrong one silently changes
+ * how a note renders.
+ *
+ * Pure and host-neutral: no editor API, no filesystem, no `node:*`. It is
+ * re-exported from `@markii/host/browser`, and
+ * `apps/vscode/src/browser-entry.probe.test.ts` is the gate for that.
+ */
+/** A container-directive fence pair enclosing an insertion point. */
+export interface EnclosingContainerFence {
+    /** Zero-based line of the opening fence, always strictly above the insertion line. */
+    readonly openLine: number;
+    /** Zero-based line of the closing fence, always strictly below the insertion line. */
+    readonly closeLine: number;
+    /** How many colons the pair is written with today (the same count on both lines). */
+    readonly colonCount: number;
+    /** Zero-based column of the first colon on the opening line. */
+    readonly openColumn: number;
+    /** Zero-based column of the first colon on the closing line. */
+    readonly closeColumn: number;
+    /** The directive name on the opening fence, e.g. `center`. */
+    readonly directiveName: string;
+}
+/**
+ * One fence line to rewrite, as data rather than an editor edit: a host
+ * turns it into whatever its own API takes, and applies the whole set in
+ * ONE undoable edit together with the insertion itself.
+ *
+ * The span is deliberately just the colon run, not the whole line: fence
+ * extension only ever ADDS colons at the start of an existing run, so the
+ * narrowest possible range keeps the edit clear of a completion item's own
+ * replace range and stays indifferent to line endings and to whatever
+ * follows on the line (`{...}` attributes, trailing whitespace).
+ */
+export interface FenceLineEdit {
+    /** Zero-based line to edit. */
+    readonly line: number;
+    /** Zero-based column where the colon run starts. */
+    readonly column: number;
+    /** The colon run as it stands today, e.g. `:::`. */
+    readonly oldText: string;
+    /** The lengthened colon run to put in its place, e.g. `::::`. */
+    readonly newText: string;
+}
+/**
+ * The container-directive fence pairs enclosing `insertionLine`, outermost
+ * first, or `undefined` for "do not touch".
+ *
+ * `undefined` is returned whenever pairing is anything but textbook: a
+ * closer with no opener, an opener left dangling at the end of the
+ * document, a closer whose colon count does not match its opener exactly,
+ * an opener that is not strictly shorter than the one it nests inside (the
+ * same-count case that does not actually nest), a `:::` run with no
+ * directive name, or an unterminated code fence.
+ *
+ * `insertionLine` itself is never read as a fence line: it is the line
+ * being edited, so mid-keystroke text on it (`:::car` on the way to
+ * `:::card`) would otherwise look like a dangling opener and suppress the
+ * very extension the author is about to need. It still advances the
+ * fenced-code state, so a cursor parked on a ``` line cannot desynchronize
+ * the scan.
+ */
+export declare function enclosingContainerFences(documentText: string, insertionLine: number): readonly EnclosingContainerFence[] | undefined;
+/**
+ * How many colons a piece of about-to-be-inserted text opens a container
+ * with, or `undefined` when it is not a container skeleton at all (a leaf
+ * or inline directive, or a bare directive name completing into an opener
+ * the author already typed). Both hosts hand this module the exact text
+ * they are about to insert, so nothing has to be re-derived from a
+ * component's kind.
+ */
+export declare function insertedContainerColonCount(insertedText: string): number | undefined;
+/**
+ * The minimal set of fence lines to lengthen so that inserting
+ * `insertedText` at `insertionLine` still nests legally, or an empty array
+ * when there is nothing to do (and for every "do not touch" case).
+ *
+ * Walking outward from the insertion point, each enclosing pair must end
+ * up strictly longer than the deepest thing now inside it. A pair that is
+ * already long enough is left alone, and stops nothing: the next pair out
+ * is measured against the count that pair actually ends up with, so
+ * lengthening cascades only as far as it has to.
+ *
+ * Edits are returned in document order and never overlap each other, and
+ * they are always on lines other than `insertionLine`, so a host can apply
+ * them alongside its own insertion (including a completion item's replace
+ * range) in one edit.
+ */
+export declare function fenceExtensionEdits(documentText: string, insertionLine: number, insertedText: string): readonly FenceLineEdit[];
+/**
+ * Whether `lineText` (the text of `documentText`'s line at `lineIndex`) is a
+ * bare colon run that CLOSES a container currently open above it, using the
+ * same textbook-pairing scan `enclosingContainerFences` uses (GitHub issue
+ * #57). A directive-name completion popup has no way on its own to tell a
+ * just-typed opener (`:::`, offer the catalog) from a pasted or typed
+ * CLOSING fence (`:::`, offer nothing) because both are the exact same bare
+ * shape; this predicate is the missing piece a completion trigger checks
+ * before opening the popup. `completionAt` itself is unaffected: it keeps
+ * offering the full catalog for a bare colon run, since it has no document
+ * context to tell the two apart.
+ *
+ * `false` for anything but a clean, currently-open match: a bare colon run
+ * with nothing open above it (a genuine opener, still worth completing), a
+ * colon run that also carries a directive name or other trailing content
+ * (`:::card`, never a closer), one whose count does not match the nearest
+ * open fence exactly, or a document whose fences do not pair cleanly above
+ * this line (an unterminated code fence, a dangling opener, an ambiguous
+ * fence) — the same "do not touch" conservatism `enclosingContainerFences`
+ * applies elsewhere in this module.
+ */
+export declare function closesOpenContainerFence(documentText: string, lineIndex: number, lineText: string): boolean;

package/dist/editor/fences/container-fences.js

@@ -0,0 +1,306 @@
+/**
+ * Fence auto-extension on insert (editor quality of life, format
+ * untouched): the pure logic behind "the outer fence pair grows when a
+ * container is inserted inside another container".
+ *
+ * docs/format.md gives container directives a fence rule borrowed from
+ * fenced code: nesting works only when the OUTER pair carries more colons
+ * than the inner one, e.g. `::::center` around `:::narrow`. Written by
+ * hand that is a chore, and getting it wrong renders the note wrong. Both
+ * hosts therefore lengthen the enclosing fences for the author, in exactly
+ * two places: the Insert Component command, and accepting a container
+ * component from the completion popup. Never while typing.
+ *
+ * The posture here is conservative on purpose. This module rewrites text
+ * the author did not ask it to touch, so it only ever acts on a document
+ * whose container fences pair cleanly from the top of the file: every
+ * opener strictly longer than the opener it nests inside, every closer
+ * matching its opener's colon count exactly, nothing left dangling at the
+ * end. Anything else, including an unterminated code fence, returns "do
+ * not touch" and the insertion proceeds exactly as it would have before.
+ * A missed extension is a small annoyance; a wrong one silently changes
+ * how a note renders.
+ *
+ * Pure and host-neutral: no editor API, no filesystem, no `node:*`. It is
+ * re-exported from `@markii/host/browser`, and
+ * `apps/vscode/src/browser-entry.probe.test.ts` is the gate for that.
+ */
+/**
+ * A block directive's colon run may be indented, but four spaces make the
+ * line an indented code block in CommonMark, so it is not a fence at all.
+ * Matching only spaces (never a tab) keeps a tab-indented line out of the
+ * fence set entirely, which is the conservative side of that ambiguity.
+ */
+const DIRECTIVE_FENCE_RE = /^( {0,3})(:{3,})(.*)$/;
+/** The character class a directive name is written in, matching `@markii/pack`'s local-name rules and `./complete/directive-context.ts`'s `NAME_CHAR`. */
+const DIRECTIVE_NAME_RE = /^[A-Za-z0-9_-]+/;
+const CODE_FENCE_RE = /^( {0,3})(`{3,}|~{3,})(.*)$/;
+/**
+ * Classifies one line, already known to be outside a code fence, as a
+ * container-directive opener, a closer, something ambiguous, or (via
+ * `undefined`) not a fence line at all. Inline (`:name[...]`) and leaf
+ * (`::name`) directives never reach three colons, so they are simply not
+ * fence lines here.
+ */
+function classifyFenceLine(text, line) {
+    const match = DIRECTIVE_FENCE_RE.exec(text);
+    if (!match)
+        return undefined;
+    const indent = match[1] ?? '';
+    const colons = match[2] ?? '';
+    const rest = match[3] ?? '';
+    const column = indent.length;
+    if (rest.trim() === '') {
+        return {
+            kind: 'close',
+            fence: { line, column, colonCount: colons.length },
+        };
+    }
+    const nameMatch = DIRECTIVE_NAME_RE.exec(rest);
+    if (!nameMatch)
+        return { kind: 'ambiguous' };
+    return {
+        kind: 'open',
+        fence: {
+            line,
+            column,
+            colonCount: colons.length,
+            directiveName: nameMatch[0],
+        },
+    };
+}
+/**
+ * Advances the fenced-code state by one line, and reports whether that
+ * line is code (or a fence delimiter) rather than something the directive
+ * scanner should look at. A ``` or ~~~ block containing `:::` lines is
+ * documentation ABOUT the format, not the format, and counting those
+ * fences would rewrite an example the author wrote deliberately.
+ */
+function stepCodeFence(state, text) {
+    const match = CODE_FENCE_RE.exec(text);
+    if (state === undefined) {
+        if (!match)
+            return { state: undefined, isCode: false };
+        const run = match[2] ?? '';
+        const info = match[3] ?? '';
+        // A backtick fence's info string may not contain a backtick (CommonMark).
+        if (run.startsWith('`') && info.includes('`')) {
+            return { state: undefined, isCode: false };
+        }
+        return { state: { char: run[0] ?? '`', length: run.length }, isCode: true };
+    }
+    if (match) {
+        const run = match[2] ?? '';
+        const info = match[3] ?? '';
+        const closes = run[0] === state.char && run.length >= state.length && info.trim() === '';
+        if (closes)
+            return { state: undefined, isCode: true };
+    }
+    return { state, isCode: true };
+}
+/** Strips one trailing `\r`, so a CRLF document classifies (and reports columns) the same as an LF one. */
+function stripCarriageReturn(line) {
+    return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
+/**
+ * The container-directive fence pairs enclosing `insertionLine`, outermost
+ * first, or `undefined` for "do not touch".
+ *
+ * `undefined` is returned whenever pairing is anything but textbook: a
+ * closer with no opener, an opener left dangling at the end of the
+ * document, a closer whose colon count does not match its opener exactly,
+ * an opener that is not strictly shorter than the one it nests inside (the
+ * same-count case that does not actually nest), a `:::` run with no
+ * directive name, or an unterminated code fence.
+ *
+ * `insertionLine` itself is never read as a fence line: it is the line
+ * being edited, so mid-keystroke text on it (`:::car` on the way to
+ * `:::card`) would otherwise look like a dangling opener and suppress the
+ * very extension the author is about to need. It still advances the
+ * fenced-code state, so a cursor parked on a ``` line cannot desynchronize
+ * the scan.
+ */
+export function enclosingContainerFences(documentText, insertionLine) {
+    if (typeof documentText !== 'string')
+        return undefined;
+    if (!Number.isInteger(insertionLine) || insertionLine < 0)
+        return undefined;
+    const lines = documentText.split('\n');
+    const stack = [];
+    const pairs = [];
+    let codeFence;
+    for (let line = 0; line < lines.length; line++) {
+        const text = stripCarriageReturn(lines[line] ?? '');
+        const stepped = stepCodeFence(codeFence, text);
+        codeFence = stepped.state;
+        if (stepped.isCode)
+            continue;
+        if (line === insertionLine)
+            continue;
+        const classified = classifyFenceLine(text, line);
+        if (classified === undefined)
+            continue;
+        if (classified.kind === 'ambiguous')
+            return undefined;
+        if (classified.kind === 'open') {
+            const parent = stack[stack.length - 1];
+            if (parent && classified.fence.colonCount >= parent.colonCount) {
+                return undefined;
+            }
+            stack.push(classified.fence);
+            continue;
+        }
+        const opener = stack.pop();
+        if (!opener)
+            return undefined;
+        if (opener.colonCount !== classified.fence.colonCount)
+            return undefined;
+        pairs.push({
+            openLine: opener.line,
+            closeLine: classified.fence.line,
+            colonCount: opener.colonCount,
+            openColumn: opener.column,
+            closeColumn: classified.fence.column,
+            directiveName: opener.directiveName,
+        });
+    }
+    if (stack.length > 0)
+        return undefined;
+    if (codeFence !== undefined)
+        return undefined;
+    return pairs
+        .filter((pair) => pair.openLine < insertionLine && pair.closeLine > insertionLine)
+        .sort((a, b) => a.openLine - b.openLine);
+}
+/**
+ * How many colons a piece of about-to-be-inserted text opens a container
+ * with, or `undefined` when it is not a container skeleton at all (a leaf
+ * or inline directive, or a bare directive name completing into an opener
+ * the author already typed). Both hosts hand this module the exact text
+ * they are about to insert, so nothing has to be re-derived from a
+ * component's kind.
+ */
+export function insertedContainerColonCount(insertedText) {
+    if (typeof insertedText !== 'string')
+        return undefined;
+    const match = /^(:{3,})[A-Za-z0-9_-]/.exec(insertedText);
+    if (!match)
+        return undefined;
+    const run = match[1] ?? '';
+    // `componentSkeleton`'s container form closes with the same run on its
+    // own last line. Anything else is not a skeleton this module built.
+    return insertedText.endsWith(`\n${run}`) ? run.length : undefined;
+}
+/**
+ * The minimal set of fence lines to lengthen so that inserting
+ * `insertedText` at `insertionLine` still nests legally, or an empty array
+ * when there is nothing to do (and for every "do not touch" case).
+ *
+ * Walking outward from the insertion point, each enclosing pair must end
+ * up strictly longer than the deepest thing now inside it. A pair that is
+ * already long enough is left alone, and stops nothing: the next pair out
+ * is measured against the count that pair actually ends up with, so
+ * lengthening cascades only as far as it has to.
+ *
+ * Edits are returned in document order and never overlap each other, and
+ * they are always on lines other than `insertionLine`, so a host can apply
+ * them alongside its own insertion (including a completion item's replace
+ * range) in one edit.
+ */
+export function fenceExtensionEdits(documentText, insertionLine, insertedText) {
+    const insertedColons = insertedContainerColonCount(insertedText);
+    if (insertedColons === undefined)
+        return [];
+    const enclosing = enclosingContainerFences(documentText, insertionLine);
+    if (enclosing === undefined || enclosing.length === 0)
+        return [];
+    const edits = [];
+    let deepestInside = insertedColons;
+    for (let i = enclosing.length - 1; i >= 0; i--) {
+        const pair = enclosing[i];
+        if (!pair)
+            continue;
+        const nextCount = Math.max(pair.colonCount, deepestInside + 1);
+        if (nextCount !== pair.colonCount) {
+            const oldText = ':'.repeat(pair.colonCount);
+            const newText = ':'.repeat(nextCount);
+            edits.push({
+                line: pair.openLine,
+                column: pair.openColumn,
+                oldText,
+                newText,
+            });
+            edits.push({
+                line: pair.closeLine,
+                column: pair.closeColumn,
+                oldText,
+                newText,
+            });
+        }
+        deepestInside = nextCount;
+    }
+    return edits.sort((a, b) => a.line - b.line);
+}
+/**
+ * Whether `lineText` (the text of `documentText`'s line at `lineIndex`) is a
+ * bare colon run that CLOSES a container currently open above it, using the
+ * same textbook-pairing scan `enclosingContainerFences` uses (GitHub issue
+ * #57). A directive-name completion popup has no way on its own to tell a
+ * just-typed opener (`:::`, offer the catalog) from a pasted or typed
+ * CLOSING fence (`:::`, offer nothing) because both are the exact same bare
+ * shape; this predicate is the missing piece a completion trigger checks
+ * before opening the popup. `completionAt` itself is unaffected: it keeps
+ * offering the full catalog for a bare colon run, since it has no document
+ * context to tell the two apart.
+ *
+ * `false` for anything but a clean, currently-open match: a bare colon run
+ * with nothing open above it (a genuine opener, still worth completing), a
+ * colon run that also carries a directive name or other trailing content
+ * (`:::card`, never a closer), one whose count does not match the nearest
+ * open fence exactly, or a document whose fences do not pair cleanly above
+ * this line (an unterminated code fence, a dangling opener, an ambiguous
+ * fence) — the same "do not touch" conservatism `enclosingContainerFences`
+ * applies elsewhere in this module.
+ */
+export function closesOpenContainerFence(documentText, lineIndex, lineText) {
+    if (typeof documentText !== 'string' || typeof lineText !== 'string') {
+        return false;
+    }
+    if (!Number.isInteger(lineIndex) || lineIndex < 0)
+        return false;
+    const classified = classifyFenceLine(stripCarriageReturn(lineText), lineIndex);
+    if (classified === undefined || classified.kind !== 'close')
+        return false;
+    const lines = documentText.split('\n');
+    const stack = [];
+    let codeFence;
+    for (let line = 0; line < lineIndex && line < lines.length; line++) {
+        const text = stripCarriageReturn(lines[line] ?? '');
+        const stepped = stepCodeFence(codeFence, text);
+        codeFence = stepped.state;
+        if (stepped.isCode)
+            continue;
+        const classifiedAbove = classifyFenceLine(text, line);
+        if (classifiedAbove === undefined)
+            continue;
+        if (classifiedAbove.kind === 'ambiguous')
+            return false;
+        if (classifiedAbove.kind === 'open') {
+            const parent = stack[stack.length - 1];
+            if (parent && classifiedAbove.fence.colonCount >= parent.colonCount) {
+                return false;
+            }
+            stack.push(classifiedAbove.fence);
+            continue;
+        }
+        const opener = stack.pop();
+        if (!opener)
+            return false;
+        if (opener.colonCount !== classifiedAbove.fence.colonCount)
+            return false;
+    }
+    if (codeFence !== undefined)
+        return false;
+    const top = stack[stack.length - 1];
+    return top !== undefined && top.colonCount === classified.fence.colonCount;
+}

package/dist/editor/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `@markii/stdlib/editor`: the pure, host-neutral editor helpers every
+ * Markii editor integration (VS Code, Obsidian, or a third-party host) is
+ * built on — directive completion and hover, the "Insert Component"
+ * skeleton builder and standard-set catalog, and fence auto-extension.
+ *
+ * This subpath, not `@markii/core`, is the home for these helpers because
+ * every one of them reads `@markii/stdlib` contract data (component kinds,
+ * required attributes, the layout vocabulary) and none of them touches
+ * `@markii/core`'s parser at all. Putting them on `@markii/core` would give
+ * the component-agnostic parser a dependency on component contracts, which
+ * is against architecture rule 1's intent (AGENTS.md); `@markii/stdlib` is
+ * already the zero-dependency contract seam every renderer implements
+ * against, so it is the natural home for the matching editor seam too.
+ *
+ * A pack-aware host composes a full catalog by appending its own pack
+ * entries after `standardComponentCatalog()`'s standard-set list (see
+ * `@markii/host`'s `insert/component-catalog.ts` for the reference
+ * composition); nothing in this subpath imports `@markii/pack`, so a host
+ * with no packs at all pays for none of it.
+ */
+export type { CompletionContext, CompletionContextKind, CompletionItem, CompletionItemKind, ComponentDocumentation, HoverInfo, } from './complete/types.js';
+export { completionAt, componentDocumentation, formatComponentDocumentation, hoverAt, } from './complete/completion.js';
+export type { AttributeNameParseResult, AttributeValueParseResult, DirectiveForm, DirectiveNameParseResult, DirectiveNameToken, ParsedCompletionContext, } from './complete/directive-context.js';
+export { clampColumn, findDirectiveNameTokenAt, parseCompletionContext, } from './complete/directive-context.js';
+export type { EditorComponentAttribute, InsertableComponent, } from './insert/component-catalog.js';
+export { LAYOUT_WRAPPER_NAMES, standardComponentCatalog, } from './insert/component-catalog.js';
+export type { ComponentSkeleton, LineColumn, } from './insert/component-skeleton.js';
+export { componentSkeleton, offsetToLineColumn, } from './insert/component-skeleton.js';
+export { firstSentence } from './insert/first-sentence.js';
+export type { EnclosingContainerFence, FenceLineEdit, } from './fences/container-fences.js';
+export { closesOpenContainerFence, enclosingContainerFences, fenceExtensionEdits, insertedContainerColonCount, } from './fences/container-fences.js';

package/dist/editor/index.js

@@ -0,0 +1,6 @@
+export { completionAt, componentDocumentation, formatComponentDocumentation, hoverAt, } from './complete/completion.js';
+export { clampColumn, findDirectiveNameTokenAt, parseCompletionContext, } from './complete/directive-context.js';
+export { LAYOUT_WRAPPER_NAMES, standardComponentCatalog, } from './insert/component-catalog.js';
+export { componentSkeleton, offsetToLineColumn, } from './insert/component-skeleton.js';
+export { firstSentence } from './insert/first-sentence.js';
+export { closesOpenContainerFence, enclosingContainerFences, fenceExtensionEdits, insertedContainerColonCount, } from './fences/container-fences.js';

package/dist/editor/insert/component-catalog.d.ts

@@ -0,0 +1,95 @@
+/**
+ * "Insert Component" (GitHub issue #17, slice 1): the standard-set half of
+ * the insert catalog — every `@markii/stdlib` standard component, split
+ * into its ordinary and layout-wrapper groups. Host-neutral and pure: no
+ * `vscode`, no `obsidian`, no filesystem access. This package has zero
+ * dependencies, so a pack's own contribution to the catalog (which needs
+ * `@markii/pack`'s manifest types) is composed one layer up, by a host
+ * (`@markii/host`'s `insert/component-catalog.ts`), which calls
+ * `standardComponentCatalog` below and appends its own pack entries after
+ * it.
+ */
+import type { ComponentKind } from '../../contracts.js';
+/**
+ * The seven layout-wrapper container directive names (docs/format.md):
+ * alignment (`center`, `left`, `right`) and width presets (`fit`, `narrow`,
+ * `wide`, `full`). Exported so a picker UI can render this group under its
+ * own heading without hand-copying the name list, and so the colocated test
+ * below can assert it stays in sync with `STANDARD_COMPONENTS`.
+ */
+export declare const LAYOUT_WRAPPER_NAMES: readonly string[];
+/**
+ * The declared shape of one attribute a discovered component contributes,
+ * structurally identical to `@markii/pack`'s `PackComponentAttribute` so
+ * that a real `PackComponentAttribute` value remains assignable here
+ * without this package depending on `@markii/pack` (this package has zero
+ * dependencies by design; only a host composing a pack-aware catalog needs
+ * the real pack types).
+ */
+export interface EditorComponentAttribute {
+    /** The name an author writes inside `{...}`, e.g. `from`. */
+    readonly name: string;
+    /** Human-readable semantics, shown in a completion row and in hover documentation. */
+    readonly description?: string;
+    /** `true` when the component is incomplete without this attribute. A required attribute is pre-filled by the insert skeleton. */
+    readonly required?: boolean;
+    /** The closed set of allowed values, when the attribute is an enum. */
+    readonly values?: readonly string[];
+    /** The value used when the attribute is absent. */
+    readonly default?: string;
+}
+/** One component a picker can offer to insert. */
+export interface InsertableComponent {
+    /** The directive name the author types, e.g. `callout`, or `cat_card` for a pack component. */
+    readonly directiveName: string;
+    readonly kind: ComponentKind;
+    readonly source: 'standard' | 'pack';
+    /**
+     * Which section of a picker this entry belongs in: the ordinary standard
+     * set, the layout-wrapper set (also `source: 'standard'`, since a layout
+     * wrapper IS a standard component — `group` is the finer split a picker
+     * UI wants), or a pack's own contribution.
+     */
+    readonly group: 'standard' | 'layout' | 'pack';
+    /** Set only when `source === 'pack'`: the owning pack's namespace. */
+    readonly packName?: string;
+    /**
+     * A short, one-line detail for a picker row, when one is available. RAW
+     * material only: a standard component's contract first sentence, or a
+     * pack component's manifest-declared `description` — never a composed
+     * filler string like `From pack "x".`. A host that wants a fallback line
+     * for a pack component with no declared description writes that string
+     * itself, in its own wording module (AGENTS.md: hosts own their
+     * user-facing strings).
+     */
+    readonly description?: string;
+    /**
+     * Required attribute names, in declaration order: a standard component's
+     * contract order, or a pack component's own `attributes` order for the
+     * entries it marked `required`. Empty when nothing is required, which is
+     * still the case for every pack that declares no attributes at all.
+     */
+    readonly requiredAttributes: readonly string[];
+    /**
+     * A pack component's declared attribute metadata (issue #27 slice 4),
+     * in the order the manifest declared it. Absent for a standard
+     * component, whose attributes come from its `@markii/stdlib` contract
+     * instead, and absent for a pack component that declared none.
+     */
+    readonly attributes?: readonly EditorComponentAttribute[];
+    /**
+     * True when `kind` came from the component's own declaration (every
+     * standard component, and a pack component whose manifest entry
+     * declares `kind`); false when `kind` is the pack-aware catalog's
+     * `'container'` default for a pack component that declared none.
+     */
+    readonly kindDeclared: boolean;
+}
+/**
+ * The standard-set half of the insert catalog: every non-layout standard
+ * component first (declaration order), then the seven layout wrappers
+ * (declaration order). A host composing a pack-aware catalog appends its
+ * own pack entries after this, using the returned list's directive names
+ * as the "already taken" set a pack component must not collide with.
+ */
+export declare function standardComponentCatalog(): readonly InsertableComponent[];

package/dist/editor/insert/component-catalog.js

@@ -0,0 +1,51 @@
+import { STANDARD_COMPONENTS } from '../../contracts.js';
+import { firstSentence } from './first-sentence.js';
+/**
+ * The seven layout-wrapper container directive names (docs/format.md):
+ * alignment (`center`, `left`, `right`) and width presets (`fit`, `narrow`,
+ * `wide`, `full`). Exported so a picker UI can render this group under its
+ * own heading without hand-copying the name list, and so the colocated test
+ * below can assert it stays in sync with `STANDARD_COMPONENTS`.
+ */
+export const LAYOUT_WRAPPER_NAMES = [
+    'center',
+    'left',
+    'right',
+    'wide',
+    'narrow',
+    'full',
+    'fit',
+];
+/** Required attribute names off a contract's `attributes` map, in the map's own key order. */
+function requiredAttributeNames(attributes) {
+    return Object.keys(attributes).filter((name) => attributes[name]?.required === true);
+}
+const LAYOUT_WRAPPER_NAME_SET = new Set(LAYOUT_WRAPPER_NAMES);
+/**
+ * Every standard component (including the layout wrappers), in
+ * `STANDARD_COMPONENTS`'s own declaration order.
+ */
+function standardCatalogEntries() {
+    return Object.entries(STANDARD_COMPONENTS).map(([name, contract]) => ({
+        directiveName: name,
+        kind: contract.kind,
+        source: 'standard',
+        group: LAYOUT_WRAPPER_NAME_SET.has(name) ? 'layout' : 'standard',
+        description: firstSentence(contract.description),
+        requiredAttributes: requiredAttributeNames(contract.attributes),
+        kindDeclared: true,
+    }));
+}
+/**
+ * The standard-set half of the insert catalog: every non-layout standard
+ * component first (declaration order), then the seven layout wrappers
+ * (declaration order). A host composing a pack-aware catalog appends its
+ * own pack entries after this, using the returned list's directive names
+ * as the "already taken" set a pack component must not collide with.
+ */
+export function standardComponentCatalog() {
+    const standardAll = standardCatalogEntries();
+    const standard = standardAll.filter((entry) => entry.group === 'standard');
+    const layout = standardAll.filter((entry) => entry.group === 'layout');
+    return [...standard, ...layout];
+}