@maias/core 0.2.0

package/dist/edit.js

@@ -0,0 +1,321 @@
+import { isMap, isSeq } from 'yaml';
+import { ORDER, orderKeys } from './fmt.js';
+import { whatLinksHere } from './graph.js';
+const ID_PATTERN = /^[a-z][a-z0-9_]*$/;
+/**
+ * Rename a screen, cascading to every reference: flows (entry_screen, screens),
+ * the navigation registry, and all targets (navigation items, elements, state
+ * elements). Edits go through the YAML document so comments and unrelated
+ * formatting are untouched — the diff is exactly the renamed references.
+ */
+export function renameScreen(parsed, oldId, newId) {
+    if (!ID_PATTERN.test(newId))
+        return { ok: false, reason: `'${newId}' is not a valid screen id (snake_case)`, changes: 0 };
+    const doc = parsed.data;
+    const screens = doc.screens ?? [];
+    if (!screens.some((s) => s?.id === oldId))
+        return { ok: false, reason: `No screen with id '${oldId}'`, changes: 0 };
+    if (screens.some((s) => s?.id === newId))
+        return { ok: false, reason: `Screen id '${newId}' already exists`, changes: 0 };
+    const paths = [];
+    screens.forEach((screen, i) => {
+        if (screen?.id === oldId)
+            paths.push(['screens', i, 'id']);
+    });
+    (doc.app?.flows ?? []).forEach((flow, i) => {
+        if (flow?.entry_screen === oldId)
+            paths.push(['app', 'flows', i, 'entry_screen']);
+        (flow?.screens ?? []).forEach((id, j) => {
+            if (id === oldId)
+                paths.push(['app', 'flows', i, 'screens', j]);
+        });
+    });
+    ['primary', 'secondary'].forEach((group) => {
+        (doc.app?.navigation?.[group]?.screens ?? []).forEach((id, j) => {
+            if (id === oldId)
+                paths.push(['app', 'navigation', group, 'screens', j]);
+        });
+    });
+    for (const ref of whatLinksHere(doc, oldId))
+        paths.push(ref.path);
+    for (const path of paths)
+        parsed.ydoc.setIn(path, newId);
+    return { ok: true, changes: paths.length };
+}
+/** Add a screen and register it. The screen object should follow canonical key order (use fmt afterwards to be sure). */
+export function addScreen(parsed, screen, opts = {}) {
+    const registry = opts.registry ?? 'secondary';
+    const doc = parsed.data;
+    if (!ID_PATTERN.test(screen?.id ?? ''))
+        return { ok: false, reason: `'${screen?.id}' is not a valid screen id (snake_case)`, changes: 0 };
+    if ((doc.screens ?? []).some((s) => s?.id === screen.id))
+        return { ok: false, reason: `Screen id '${screen.id}' already exists`, changes: 0 };
+    if (opts.flow && !(doc.app?.flows ?? []).some((f) => f?.name === opts.flow)) {
+        return { ok: false, reason: `No flow named '${opts.flow}'`, changes: 0 };
+    }
+    let changes = 0;
+    parsed.ydoc.addIn(['screens'], parsed.ydoc.createNode(screen));
+    changes++;
+    parsed.ydoc.addIn(['app', 'navigation', registry, 'screens'], parsed.ydoc.createNode(screen.id));
+    changes++;
+    if (opts.flow) {
+        const flowIndex = (doc.app?.flows ?? []).findIndex((f) => f?.name === opts.flow);
+        parsed.ydoc.addIn(['app', 'flows', flowIndex, 'screens'], parsed.ydoc.createNode(screen.id));
+        changes++;
+    }
+    return { ok: true, changes };
+}
+/** Remove a screen plus its registry and flow entries. Safe by default: refuses to leave dangling targets. */
+export function removeScreen(parsed, id, opts = {}) {
+    const doc = parsed.data;
+    if (!(doc.screens ?? []).some((s) => s?.id === id)) {
+        return { ok: false, reason: `No screen with id '${id}'`, changes: 0, inboundRefs: [] };
+    }
+    const inboundRefs = whatLinksHere(doc, id);
+    if (inboundRefs.length > 0 && !opts.cascade) {
+        return {
+            ok: false,
+            reason: `${inboundRefs.length} reference(s) point at '${id}' (from: ${[...new Set(inboundRefs.map((r) => r.from))].join(', ')}) — remove them or pass cascade`,
+            changes: 0,
+            inboundRefs,
+        };
+    }
+    // Collect every deletion as a path, then apply children-first / high-index-first
+    // so earlier deletions never shift later ones.
+    const deletions = [];
+    (doc.screens ?? []).forEach((screen, i) => {
+        if (screen?.id === id)
+            deletions.push(['screens', i]);
+    });
+    (doc.app?.flows ?? []).forEach((flow, i) => {
+        (flow?.screens ?? []).forEach((sid, j) => {
+            if (sid === id)
+                deletions.push(['app', 'flows', i, 'screens', j]);
+        });
+    });
+    ['primary', 'secondary'].forEach((group) => {
+        (doc.app?.navigation?.[group]?.screens ?? []).forEach((sid, j) => {
+            if (sid === id)
+                deletions.push(['app', 'navigation', group, 'screens', j]);
+        });
+    });
+    for (const ref of inboundRefs) {
+        if (ref.kind === 'element' || ref.kind === 'state_element') {
+            // The element survives, it just no longer navigates.
+            deletions.push(ref.path);
+        }
+        else {
+            // Navigation items and back links are objects around their target; delete the whole thing.
+            deletions.push(ref.path.slice(0, -1));
+        }
+    }
+    deletions
+        .sort(comparePathsForDeletion)
+        .forEach((path) => parsed.ydoc.deleteIn(path));
+    return { ok: true, changes: deletions.length, inboundRefs };
+}
+const STATE_KEYS = ['empty', 'loading', 'error'];
+/**
+ * Edit a screen's `elements` list (or a declared state's list) in place:
+ * insert, update, remove, move. The batch is atomic — every op is checked
+ * against a simulated copy first, so a failing op leaves the document
+ * untouched. Ops apply sequentially: each op's `index` addresses the list as
+ * left by the previous ops. Safe by default: an op that would introduce a
+ * `target` not matching any screen is refused, as is editing a state the
+ * screen does not declare (declaring states is a screen-shape decision).
+ */
+export function editElements(parsed, screenId, ops) {
+    const doc = parsed.data;
+    const screens = doc.screens ?? [];
+    const screenIdx = screens.findIndex((s) => s?.id === screenId);
+    if (screenIdx === -1)
+        return { ok: false, reason: `No screen with id '${screenId}'`, changes: 0 };
+    if (ops.length === 0)
+        return { ok: false, reason: 'No operations given', changes: 0 };
+    const screen = screens[screenIdx];
+    const screenIds = new Set(screens.map((s) => s?.id));
+    // Pass 1 — validate every op against simulated lists; nothing is written unless all pass.
+    const sim = new Map();
+    const listFor = (state) => {
+        const key = state ?? '';
+        if (!sim.has(key)) {
+            const source = state ? screen.states?.[state]?.elements : screen.elements;
+            sim.set(key, (source ?? []).map((e) => ({ type: e?.type, label: e?.label })));
+        }
+        return sim.get(key);
+    };
+    for (let i = 0; i < ops.length; i++) {
+        const o = ops[i];
+        const listName = o.state ? `states.${o.state}.elements` : 'elements';
+        const fail = (message) => ({ ok: false, reason: `op ${i} (${o.op}): ${message}`, changes: 0 });
+        if (o.state !== undefined) {
+            if (!STATE_KEYS.includes(o.state))
+                return fail(`'${o.state}' is not a state (empty | loading | error)`);
+            const variant = screen.states?.[o.state];
+            if (variant == null || typeof variant !== 'object') {
+                return fail(`screen '${screenId}' does not declare state '${o.state}' — add the state to the screen first`);
+            }
+        }
+        const list = listFor(o.state);
+        if (!Number.isInteger(o.index) || o.index < 0)
+            return fail(`index must be a non-negative integer, got ${o.index}`);
+        // Address check: insert may point one past the end (append); everything else needs an existing element.
+        const maxIndex = o.op === 'insert' ? list.length : list.length - 1;
+        if (o.index > maxIndex) {
+            return fail(`index ${o.index} out of range — ${listName} of '${screenId}' has ${list.length} element(s)`);
+        }
+        if (o.op !== 'insert' && o.expect) {
+            const found = list[o.index];
+            const mismatch = (o.expect.type !== undefined && o.expect.type !== found.type) ||
+                (o.expect.label !== undefined && o.expect.label !== found.label);
+            if (mismatch) {
+                return fail(`guard mismatch at ${listName}[${o.index}] of '${screenId}' — found type '${found.type}', label '${found.label}'`);
+            }
+        }
+        switch (o.op) {
+            case 'insert': {
+                const shapeError = checkElementFields(o.element, { requireType: true });
+                if (shapeError)
+                    return fail(shapeError);
+                const target = o.element?.target;
+                if (typeof target === 'string' && !screenIds.has(target)) {
+                    return fail(`target '${target}' does not match any screen`);
+                }
+                list.splice(o.index, 0, { type: o.element.type, label: o.element.label });
+                break;
+            }
+            case 'update': {
+                if (!o.set || Object.keys(o.set).length === 0)
+                    return fail('set must contain at least one key');
+                if ('type' in o.set && o.set.type == null)
+                    return fail(`'type' cannot be deleted`);
+                const shapeError = checkElementFields(o.set, { allowNull: true });
+                if (shapeError)
+                    return fail(shapeError);
+                if (typeof o.set.target === 'string' && !screenIds.has(o.set.target)) {
+                    return fail(`target '${o.set.target}' does not match any screen`);
+                }
+                const el = list[o.index];
+                if ('type' in o.set)
+                    el.type = o.set.type;
+                if ('label' in o.set)
+                    el.label = o.set.label ?? undefined;
+                break;
+            }
+            case 'remove':
+                list.splice(o.index, 1);
+                break;
+            case 'move': {
+                if (!Number.isInteger(o.to) || o.to < 0 || o.to >= list.length) {
+                    return fail(`'to' ${o.to} out of range — ${listName} of '${screenId}' has ${list.length} element(s)`);
+                }
+                const [el] = list.splice(o.index, 1);
+                list.splice(o.to, 0, el);
+                break;
+            }
+            default:
+                return fail(`unknown operation '${o.op}'`);
+        }
+    }
+    // Pass 2 — apply to the YAML document (comments and unrelated formatting untouched).
+    const screenPath = ['screens', screenIdx];
+    const seqPath = (state) => state ? [...screenPath, 'states', state, 'elements'] : [...screenPath, 'elements'];
+    const seqAt = (state) => {
+        const node = parsed.ydoc.getIn(seqPath(state));
+        return isSeq(node) ? node : undefined;
+    };
+    for (const o of ops) {
+        switch (o.op) {
+            case 'insert': {
+                const node = parsed.ydoc.createNode(canonicalElementLiteral(o.element));
+                const seq = seqAt(o.state);
+                if (seq) {
+                    seq.items.splice(o.index, 0, node);
+                }
+                else {
+                    // No `elements` key yet (screen without one, or documentation-only state):
+                    // create it, then restore canonical key order in the parent map.
+                    parsed.ydoc.setIn(seqPath(o.state), parsed.ydoc.createNode([]));
+                    seqAt(o.state).items.splice(0, 0, node);
+                    const parentPath = o.state ? [...screenPath, 'states', o.state] : screenPath;
+                    const parent = parsed.ydoc.getIn(parentPath);
+                    if (isMap(parent))
+                        orderKeys(parent, o.state ? ORDER.stateVariant : ORDER.screen);
+                }
+                break;
+            }
+            case 'update': {
+                const itemPath = [...seqPath(o.state), o.index];
+                for (const [key, value] of Object.entries(o.set)) {
+                    if (value === null)
+                        parsed.ydoc.deleteIn([...itemPath, key]);
+                    else
+                        parsed.ydoc.setIn([...itemPath, key], value);
+                }
+                const item = parsed.ydoc.getIn(itemPath);
+                if (isMap(item))
+                    orderKeys(item, ORDER.item);
+                break;
+            }
+            case 'remove': {
+                parsed.ydoc.deleteIn([...seqPath(o.state), o.index]);
+                // Omit-empty (spec §11.1): a now-empty list drops its key entirely.
+                if (seqAt(o.state)?.items.length === 0)
+                    parsed.ydoc.deleteIn(seqPath(o.state));
+                break;
+            }
+            case 'move': {
+                const seq = seqAt(o.state);
+                const [node] = seq.items.splice(o.index, 1);
+                seq.items.splice(o.to, 0, node);
+                break;
+            }
+        }
+    }
+    return { ok: true, changes: ops.length };
+}
+/** Scalar sanity for the four known element fields; deep shape errors stay validator territory. */
+function checkElementFields(fields, opts = {}) {
+    if (!fields || typeof fields !== 'object')
+        return 'element requires an object with at least a type';
+    if (opts.requireType && (typeof fields.type !== 'string' || fields.type === '')) {
+        return `element requires a non-empty 'type'`;
+    }
+    for (const key of ['label', 'type', 'target', 'presentation']) {
+        const value = fields[key];
+        if (value === undefined)
+            continue;
+        if (value === null && opts.allowNull)
+            continue;
+        if (typeof value !== 'string')
+            return `'${key}' must be a string, got ${JSON.stringify(value)}`;
+    }
+    return undefined;
+}
+/** Element literal with canonical key order (label, type, target, presentation, then x_ in author order). */
+function canonicalElementLiteral(element) {
+    const out = {};
+    const source = element;
+    for (const key of ORDER.item) {
+        if (source[key] !== undefined)
+            out[key] = source[key];
+    }
+    for (const [key, value] of Object.entries(element)) {
+        if (!(key in out) && value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/** Deeper paths first; within the same container, higher indices first. */
+function comparePathsForDeletion(a, b) {
+    if (a.length !== b.length)
+        return b.length - a.length;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] === b[i])
+            continue;
+        if (typeof a[i] === 'number' && typeof b[i] === 'number')
+            return b[i] - a[i];
+        return String(a[i]).localeCompare(String(b[i]));
+    }
+    return 0;
+}

package/dist/fmt.d.ts

@@ -0,0 +1,27 @@
+import { type YAMLMap } from 'yaml';
+import type { ParsedDocument } from './parse.js';
+/**
+ * Canonical form (spec chapter 11): fixed key order per object kind, derived
+ * screen ordering, omit-empty/default keys, quoted version header. Mutates the
+ * underlying YAML document; comments move with their nodes. Idempotent.
+ */
+export declare function canonicalize(parsed: ParsedDocument): ParsedDocument;
+/** Canonical text for the document (fmt = canonicalize + serialise). */
+export declare function format(parsed: ParsedDocument): string;
+/** Canonical key order per object kind (spec §11.1). Shared with edit.ts; not part of the package surface. */
+export declare const ORDER: {
+    root: string[];
+    app: string[];
+    links: string[];
+    registry: string[];
+    navGroup: string[];
+    flow: string[];
+    screen: string[];
+    screenNav: string[];
+    item: string[];
+    states: string[];
+    stateVariant: string[];
+    data: string[];
+};
+/** Reorder pairs: known keys in table order, then x_/unknown keys in author order. */
+export declare function orderKeys(map: YAMLMap, order: string[]): void;

package/dist/fmt.js

@@ -0,0 +1,257 @@
+import { isMap, isScalar, isSeq, Scalar } from 'yaml';
+/**
+ * Canonical form (spec chapter 11): fixed key order per object kind, derived
+ * screen ordering, omit-empty/default keys, quoted version header. Mutates the
+ * underlying YAML document; comments move with their nodes. Idempotent.
+ */
+export function canonicalize(parsed) {
+    const root = parsed.ydoc.contents;
+    if (!isMap(root))
+        return parsed;
+    orderKeys(root, ORDER.root);
+    quoteVersionHeader(root);
+    forceBlockStyle(root);
+    const app = getMap(root, 'app');
+    if (app) {
+        orderKeys(app, ORDER.app);
+        const links = getMap(app, 'links');
+        if (links)
+            orderKeys(links, ORDER.links);
+        const navigation = getMap(app, 'navigation');
+        if (navigation) {
+            orderKeys(navigation, ORDER.registry);
+            for (const group of ['primary', 'secondary']) {
+                const groupMap = getMap(navigation, group);
+                if (groupMap)
+                    orderKeys(groupMap, ORDER.navGroup);
+            }
+        }
+        const flows = getSeq(app, 'flows');
+        if (flows)
+            for (const flow of flows.items)
+                if (isMap(flow))
+                    orderKeys(flow, ORDER.flow);
+    }
+    const screens = getSeq(root, 'screens');
+    if (screens) {
+        for (const screen of screens.items)
+            if (isMap(screen))
+                canonicalizeScreen(screen);
+        reorderScreens(parsed, screens);
+        syncSecondaryRegistry(parsed, root);
+        dropEmptyKeys(screens);
+    }
+    return parsed;
+}
+/** Canonical text for the document (fmt = canonicalize + serialise). */
+export function format(parsed) {
+    canonicalize(parsed);
+    return parsed.toString();
+}
+/** Canonical key order per object kind (spec §11.1). Shared with edit.ts; not part of the package surface. */
+export const ORDER = {
+    root: ['maias', 'app', 'screens'],
+    app: ['name', 'description', 'links', 'navigation', 'flows'],
+    links: ['scheme'],
+    registry: ['primary', 'secondary'],
+    navGroup: ['label', 'screens'],
+    flow: ['name', 'description', 'entry_screen', 'screens'],
+    screen: ['id', 'title', 'type', 'path', 'description', 'presentation', 'auth', 'deep_link', 'back', 'features', 'actions', 'elements', 'states', 'navigation', 'data'],
+    screenNav: ['primary', 'secondary', 'actions'],
+    item: ['label', 'type', 'target', 'presentation', 'external'],
+    states: ['empty', 'loading', 'error'],
+    stateVariant: ['description', 'elements'],
+    data: ['reads', 'writes'],
+};
+function canonicalizeScreen(screen) {
+    orderKeys(screen, ORDER.screen);
+    removeDefaults(screen);
+    const back = getMap(screen, 'back');
+    if (back)
+        orderKeys(back, ORDER.item);
+    const elements = getSeq(screen, 'elements');
+    if (elements)
+        canonicalizeItems(elements);
+    const states = getMap(screen, 'states');
+    if (states) {
+        orderKeys(states, ORDER.states);
+        for (const state of ['empty', 'loading', 'error']) {
+            const variant = getMap(states, state);
+            if (variant) {
+                orderKeys(variant, ORDER.stateVariant);
+                const stateElements = getSeq(variant, 'elements');
+                if (stateElements)
+                    canonicalizeItems(stateElements);
+            }
+        }
+    }
+    const navigation = getMap(screen, 'navigation');
+    if (navigation) {
+        orderKeys(navigation, ORDER.screenNav);
+        for (const group of ['primary', 'secondary', 'actions']) {
+            const items = getSeq(navigation, group);
+            if (items)
+                canonicalizeItems(items);
+        }
+    }
+    const data = getMap(screen, 'data');
+    if (data)
+        orderKeys(data, ORDER.data);
+}
+function canonicalizeItems(seq) {
+    for (const item of seq.items) {
+        if (isMap(item)) {
+            orderKeys(item, ORDER.item);
+            removeDefaults(item);
+        }
+    }
+}
+/** Reorder pairs: known keys in table order, then x_/unknown keys in author order. */
+export function orderKeys(map, order) {
+    const rank = (pair) => {
+        const key = keyOf(pair);
+        const i = order.indexOf(key);
+        return i === -1 ? order.length : i;
+    };
+    // Stable sort keeps author order for keys outside the table (x_ extensions).
+    map.items = map.items
+        .map((pair, i) => ({ pair, i }))
+        .sort((a, b) => rank(a.pair) - rank(b.pair) || a.i - b.i)
+        .map(({ pair }) => pair);
+}
+/**
+ * Spec §11.1: block style everywhere — never inline (`[]`/`{}`) collections.
+ * Clears the flow flag on every non-empty map/seq so authored inline
+ * collections serialise as block. Empty collections keep flow style — `[]` is
+ * their only sensible rendering (schema-required empties like the calculator's
+ * secondary registry stay `screens: []`; optional empties are dropped by
+ * pruneEmpty anyway).
+ */
+function forceBlockStyle(node) {
+    if (isMap(node)) {
+        if (node.items.length > 0)
+            node.flow = false;
+        for (const pair of node.items)
+            forceBlockStyle(pair.value);
+    }
+    else if (isSeq(node)) {
+        if (node.items.length > 0)
+            node.flow = false;
+        for (const item of node.items)
+            forceBlockStyle(item);
+    }
+}
+/** Spec §11.1: omit keys at their default value. */
+function removeDefaults(map) {
+    map.items = map.items.filter((pair) => {
+        const key = keyOf(pair);
+        const value = isScalar(pair.value) ? pair.value.value : undefined;
+        if (key === 'deep_link' && value === false)
+            return false;
+        if (key === 'auth' && value === 'none')
+            return false;
+        if (key === 'presentation' && value === 'push')
+            return false;
+        if (key === 'external' && value === false)
+            return false;
+        return true;
+    });
+}
+/**
+ * Spec §11.1: omit empty collections, and the legacy `- None` placeholder lists
+ * for features/actions. Applied to screen subtrees (where every collection is
+ * optional) — recursing bottom-up so `data: {reads: [], writes: []}` collapses
+ * away entirely. Registry and flow lists are schema-required and untouched.
+ */
+function dropEmptyKeys(screens) {
+    for (const screen of screens.items) {
+        if (!isMap(screen))
+            continue;
+        pruneEmpty(screen);
+    }
+}
+function pruneEmpty(map) {
+    map.items = map.items.filter((pair) => {
+        const value = pair.value;
+        if (isMap(value)) {
+            pruneEmpty(value);
+            return value.items.length > 0;
+        }
+        if (isSeq(value)) {
+            if (value.items.length === 0)
+                return false;
+            const key = keyOf(pair);
+            if ((key === 'actions' || key === 'features') && value.items.length === 1) {
+                const only = value.items[0];
+                if (isScalar(only) && (only.value === 'None' || only.value === 'none'))
+                    return false;
+            }
+        }
+        return true;
+    });
+}
+/**
+ * Spec §11.2: screens ordered by flow membership — flows in document order,
+ * screens in within-flow order, multi-flow screens under their first flow,
+ * flowless screens last sorted by id. Fully derived, so formatters converge.
+ */
+function reorderScreens(parsed, screens) {
+    const doc = parsed.data;
+    const currentIds = (doc.screens ?? []).map((s) => s?.id);
+    const placed = new Set();
+    const desired = [];
+    for (const flow of doc.app?.flows ?? []) {
+        for (const id of flow?.screens ?? []) {
+            if (typeof id === 'string' && currentIds.includes(id) && !placed.has(id)) {
+                placed.add(id);
+                desired.push(id);
+            }
+        }
+    }
+    const rest = currentIds.filter((id) => typeof id === 'string' && !placed.has(id)).sort();
+    desired.push(...rest);
+    const byId = new Map();
+    screens.items.forEach((item, i) => {
+        const id = currentIds[i];
+        if (typeof id === 'string' && !byId.has(id))
+            byId.set(id, item);
+    });
+    // Only reorder if every screen resolved cleanly (duplicates/invalid shapes are validator territory).
+    if (byId.size === screens.items.length) {
+        screens.items = desired.map((id) => byId.get(id));
+    }
+}
+/** Spec §11.2: secondary registry list follows the screens ordering; primary keeps tab order. */
+function syncSecondaryRegistry(parsed, root) {
+    const doc = parsed.data;
+    const screenOrder = new Map((doc.screens ?? []).map((s, i) => [s?.id, i]));
+    const navigation = getMap(root, 'app') && getMap(getMap(root, 'app'), 'navigation');
+    const secondary = navigation && getMap(navigation, 'secondary');
+    const list = secondary && getSeq(secondary, 'screens');
+    if (!list)
+        return;
+    const ids = list.items.filter(isScalar);
+    if (ids.length !== list.items.length)
+        return;
+    list.items = [...list.items].sort((a, b) => {
+        const ai = screenOrder.get(a.value) ?? Number.MAX_SAFE_INTEGER;
+        const bi = screenOrder.get(b.value) ?? Number.MAX_SAFE_INTEGER;
+        return ai - bi;
+    });
+}
+function quoteVersionHeader(root) {
+    const pair = root.items.find((p) => keyOf(p) === 'maias');
+    if (pair && isScalar(pair.value))
+        pair.value.type = Scalar.QUOTE_DOUBLE;
+}
+function keyOf(pair) {
+    return isScalar(pair.key) ? String(pair.key.value) : String(pair.key);
+}
+function getMap(map, key) {
+    const value = map.get(key, true);
+    return isMap(value) ? value : undefined;
+}
+function getSeq(map, key) {
+    const value = map.get(key, true);
+    return isSeq(value) ? value : undefined;
+}

package/dist/graph.d.ts

@@ -0,0 +1,29 @@
+import type { MaiasDocument, DocPath, Screen } from './model.js';
+/** One outbound reference from a screen to another screen. */
+export interface OutboundRef {
+    /** Screen the reference points at (the `target`). */
+    target: string;
+    /** Where the reference lives. */
+    kind: 'navigation.primary' | 'navigation.secondary' | 'element' | 'state_element' | 'back';
+    label?: string;
+    /** JSON path to the target scalar, relative to the document root. */
+    path: DocPath;
+}
+export interface InboundRef extends OutboundRef {
+    /** Screen the reference lives on. */
+    from: string;
+}
+/** All screen-to-screen references declared on a screen (nav items, elements, state elements). */
+export declare function outboundRefs(screen: Screen, screenIndex: number): OutboundRef[];
+/** Index of screens by ID. First occurrence wins when IDs are duplicated (lint reports the duplicate). */
+export declare function screenIndex(doc: MaiasDocument): Map<string, Screen>;
+export declare function getScreen(doc: MaiasDocument, id: string): Screen | undefined;
+/**
+ * Screens reachable from the app's structure (spec §3.3): primary navigation,
+ * flow entry screens, then transitively via outbound references.
+ */
+export declare function reachableScreens(doc: MaiasDocument): Set<string>;
+/** Screens in no flow AND unreachable (spec §3.2). */
+export declare function orphanScreens(doc: MaiasDocument): string[];
+/** All references across the document pointing at `id`. */
+export declare function whatLinksHere(doc: MaiasDocument, id: string): InboundRef[];