@wootsup/yt-builder-mcp 0.2.0-alpha.2

package/dist/tools/format/sources-format.js

@@ -0,0 +1,113 @@
+/**
+ * Sources format-sidecar — pure transforms for `sources_list` (table) and
+ * `element_get_binding` (detail). Wave G.2.7 (Design §3.2 rows 16 / 17).
+ *
+ * @license MIT
+ */
+// ─── sources_list columns (Design §3.2 row 16) ───────────────────────
+export const SOURCES_TABLE_COLUMNS = [
+    { key: 'name', label: 'NAME', width: 36, llmOnly: true },
+    { key: 'label', label: 'LABEL', width: 28 },
+    { key: 'origin', label: 'ORIGIN', width: 12 },
+    { key: 'kind', label: 'KIND', width: 10 },
+];
+// ─── Row mapper ──────────────────────────────────────────────────────
+function asString(v) {
+    return typeof v === 'string' ? v : '';
+}
+export function mapSourceRow(input) {
+    return {
+        name: asString(input.name),
+        label: asString(input.label),
+        origin: asString(input.origin),
+        kind: asString(input.kind),
+    };
+}
+/**
+ * The REST plugin exposes sources EITHER as a grouped object
+ * `{apimapper:[…], wordpress:[…], essentials:[…]}` OR (post-refactor)
+ * as a flat array of `{name, label, origin, kind}`. This helper
+ * normalises both into a flat array — flattening adds `origin` from the
+ * group key when absent.
+ */
+const KNOWN_ORIGINS = ['apimapper', 'wordpress', 'essentials'];
+export function flattenSourcesPayload(payload) {
+    if (Array.isArray(payload)) {
+        return payload.filter((x) => x !== null && typeof x === 'object');
+    }
+    if (payload !== null && typeof payload === 'object') {
+        const out = [];
+        const obj = payload;
+        for (const origin of KNOWN_ORIGINS) {
+            const group = obj[origin];
+            if (Array.isArray(group)) {
+                for (const item of group) {
+                    if (item !== null && typeof item === 'object') {
+                        const rec = item;
+                        out.push({ origin, ...rec });
+                    }
+                }
+            }
+        }
+        return out;
+    }
+    return [];
+}
+// ─── Detail builder (Design §3.2 row 17) ─────────────────────────────
+export function buildBindingDetail(payload) {
+    const b = payload.binding;
+    const sourceName = typeof b.source_name === 'string' ? b.source_name : null;
+    const configCount = b.source_config !== null && typeof b.source_config === 'object'
+        ? Object.keys(b.source_config).length
+        : 0;
+    const argsCount = b.source_args !== null && typeof b.source_args === 'object'
+        ? Object.keys(b.source_args).length
+        : 0;
+    return {
+        title: `Binding for ${payload.element_path}`,
+        groups: [
+            {
+                label: 'Element',
+                entries: [
+                    {
+                        key: 'template_id',
+                        label: 'Template',
+                        value: payload.template_id,
+                        format: 'badge',
+                    },
+                    {
+                        key: 'element_path',
+                        label: 'Path',
+                        value: payload.element_path,
+                        format: 'code',
+                        copyable: true,
+                    },
+                ],
+            },
+            {
+                label: 'Binding',
+                entries: [
+                    {
+                        key: 'source_name',
+                        label: 'Source',
+                        value: sourceName,
+                        format: 'badge',
+                    },
+                    {
+                        key: 'config_keys',
+                        label: 'Config keys',
+                        value: configCount,
+                        format: 'text',
+                    },
+                    {
+                        key: 'args_keys',
+                        label: 'Args keys',
+                        value: argsCount,
+                        format: 'text',
+                    },
+                ],
+            },
+        ],
+    };
+}
+//# sourceMappingURL=sources-format.js.map

package/dist/tools/format/sources-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources-format.js","sourceRoot":"","sources":["../../../src/tools/format/sources-format.ts"],"names":[],"mappings":"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"}

package/dist/tools/health.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Health & diagnostics tools.
+ *
+ *   yootheme_builder_health
+ *      → GET /health (unauthenticated). Verifies the plugin is
+ *        installed and reachable. Returns plugin/YT/WP/PHP versions
+ *        + available endpoints.
+ *
+ *   yootheme_builder_diagnose
+ *      → Aggregates health + a Bearer-auth probe so the agent can
+ *        distinguish "plugin missing" from "wrong key".
+ *
+ * Both tools emit `detailResult` (Wave G.2) so hosts that support
+ * structured content render a Detail-Card; the LLM still reads the text
+ * leg from `content[0].text`.
+ *
+ * @license MIT
+ */
+import type { RestClient } from '../client.js';
+import { type AnyToolDefinition } from './tool-builder.js';
+export declare function buildHealthTools(client: RestClient): readonly AnyToolDefinition[];
+//# sourceMappingURL=health.d.ts.map

package/dist/tools/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/tools/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAQ/C,OAAO,EAMH,KAAK,iBAAiB,EACzB,MAAM,mBAAmB,CAAC;AA2B3B,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CAyGjF"}

package/dist/tools/health.js

@@ -0,0 +1,147 @@
+/**
+ * Health & diagnostics tools.
+ *
+ *   yootheme_builder_health
+ *      → GET /health (unauthenticated). Verifies the plugin is
+ *        installed and reachable. Returns plugin/YT/WP/PHP versions
+ *        + available endpoints.
+ *
+ *   yootheme_builder_diagnose
+ *      → Aggregates health + a Bearer-auth probe so the agent can
+ *        distinguish "plugin missing" from "wrong key".
+ *
+ * Both tools emit `detailResult` (Wave G.2) so hosts that support
+ * structured content render a Detail-Card; the LLM still reads the text
+ * leg from `content[0].text`.
+ *
+ * @license MIT
+ */
+import { detailResult, statsResult } from '@getimo/mcp-toolkit';
+import { z } from 'zod';
+import { RestError } from '../errors.js';
+import { buildDiagnoseDetail, buildHealthStats, } from './format/health-format.js';
+import { defineTool, errorResult, jsonResult, readOnly, structuredResult, } from './tool-builder.js';
+// ─── outputSchemas (Wave G.2 §4) ─────────────────────────────────────
+const HEALTH_OUTPUT_SCHEMA = z.object({
+    plugin_version: z.string(),
+    yootheme_version: z.string().nullable(),
+    wp_version: z.string().nullable(),
+    php_version: z.string(),
+    storage_type: z.string(),
+    storage_target: z.string(),
+    yootheme_loaded: z.boolean(),
+    available_endpoints: z.array(z.string()),
+});
+const DIAGNOSE_OUTPUT_SCHEMA = z.object({
+    plugin_reachable: z.boolean(),
+    plugin_version: z.string().optional(),
+    yootheme_loaded: z.boolean().optional(),
+    yootheme_version: z.string().nullable().optional(),
+    endpoint_count: z.number().optional(),
+    plugin_error: z.string().optional(),
+    bearer_valid: z.boolean().optional(),
+    bearer_error: z.string().optional(),
+    summary: z.string().optional(),
+});
+export function buildHealthTools(client) {
+    return [
+        defineTool({
+            name: 'yootheme_builder_health',
+            description: 'Check that the YT Builder MCP plugin is installed and reachable. ' +
+                'Returns plugin version, YOOtheme Pro version (if loaded), and the list of ' +
+                'available REST endpoints. Unauthenticated probe — call this first when ' +
+                'troubleshooting connectivity.',
+            inputSchema: {},
+            outputSchema: HEALTH_OUTPUT_SCHEMA,
+            annotations: readOnly('Health Check'),
+            handler: async () => {
+                try {
+                    const data = await client.get('/health');
+                    // Round-1 audit I1 fix: spec §3.2 row 1 calls for
+                    // `statsResult` (flat metrics). Earlier shipped
+                    // `detailResult` — that's a Detail-Card variant, not
+                    // the stats-display the spec asked for. The flat
+                    // shape is built by `buildHealthStats`.
+                    const toolkitResult = statsResult(buildHealthStats(data));
+                    return structuredResult(toolkitResult, {
+                        plugin_version: data.plugin_version,
+                        yootheme_version: data.yootheme_version,
+                        wp_version: data.wp_version,
+                        php_version: data.php_version,
+                        storage_type: data.storage_type,
+                        storage_target: data.storage_target,
+                        yootheme_loaded: data.yootheme_loaded,
+                        available_endpoints: data.available_endpoints,
+                    });
+                }
+                catch (e) {
+                    return errorResult({
+                        error: e,
+                        context: {},
+                        hint: 'Verify YTB_MCP_WP_URL points at a WordPress site with the ' +
+                            'yt-builder-mcp plugin active. Try opening ' +
+                            '<wp_url>/wp-json/yt-builder-mcp/v1/health in a browser.',
+                    });
+                }
+            },
+        }),
+        defineTool({
+            name: 'yootheme_builder_diagnose',
+            description: 'Run a full diagnostic: hit /health (no auth), then attempt an authenticated ' +
+                'call (/etag) to confirm the Bearer key is valid. Use when health passes but ' +
+                'tools return 401/403.',
+            inputSchema: {},
+            outputSchema: DIAGNOSE_OUTPUT_SCHEMA,
+            annotations: readOnly('Diagnose Connection'),
+            handler: async () => {
+                const checks = { plugin_reachable: false };
+                try {
+                    const health = await client.get('/health');
+                    checks.plugin_reachable = true;
+                    checks.plugin_version = health.plugin_version;
+                    checks.yootheme_loaded = health.yootheme_loaded;
+                    checks.yootheme_version = health.yootheme_version;
+                    checks.endpoint_count = health.available_endpoints.length;
+                }
+                catch (e) {
+                    checks.plugin_reachable = false;
+                    checks.plugin_error = e instanceof Error ? e.message : String(e);
+                    // Plugin-unreachable path stays on jsonResult so the LLM
+                    // sees the structured error hint inline (detailResult would
+                    // hide the actionable "verify YTB_MCP_WP_URL" hint inside
+                    // a sub-group). isError=true preserves SDK semantics.
+                    return jsonResult({
+                        ...checks,
+                        hint: 'Plugin not reachable. Verify YTB_MCP_WP_URL and that the ' +
+                            'yt-builder-mcp WordPress plugin is active.',
+                    }, { isError: true });
+                }
+                try {
+                    await client.get('/etag');
+                    checks.bearer_valid = true;
+                }
+                catch (e) {
+                    checks.bearer_valid = false;
+                    if (e instanceof RestError) {
+                        checks.bearer_error = `HTTP ${String(e.status)}: ${e.message}`;
+                    }
+                    else {
+                        checks.bearer_error = e instanceof Error ? e.message : String(e);
+                    }
+                    return jsonResult({
+                        ...checks,
+                        hint: 'Bearer key rejected. Regenerate the key in wp-admin → Tools → ' +
+                            '"YT Builder MCP" → Bearer Keys and re-run ' +
+                            '`yt-builder-mcp setup`.',
+                    }, { isError: true });
+                }
+                const toolkitResult = detailResult(buildDiagnoseDetail(checks));
+                return structuredResult(toolkitResult, {
+                    ...checks,
+                    summary: 'OK — plugin reachable and Bearer key accepted.',
+                });
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=health.js.map

package/dist/tools/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/tools/health.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool aggregator — collects all domain tools into a single list.
+ * The MCP server iterates this list at startup to register handlers
+ * with `@modelcontextprotocol/sdk`.
+ *
+ * @license MIT
+ */
+import type { RestClient } from '../client.js';
+import type { McpServerWithElicitation } from './elicitation.js';
+import type { AnyToolDefinition } from './tool-builder.js';
+export interface BuildAllToolsOptions {
+    /**
+     * Optional MCP elicitation capability — see
+     * `src/tools/elicitation.ts` for the adapter. When supplied,
+     * destructive + ambiguity-resolution tools prompt the user via the
+     * elicitation channel; when omitted, they fall back to the
+     * preview-then-retry / `ambiguityFallbackError` flow.
+     */
+    readonly elicitation?: McpServerWithElicitation;
+}
+export declare function buildAllTools(client: RestClient, options?: BuildAllToolsOptions): readonly AnyToolDefinition[];
+export type { AnyToolDefinition, ToolDefinition } from './tool-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAKjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACnD;AAED,wBAAgB,aAAa,CACzB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,oBAAyB,GACnC,SAAS,iBAAiB,EAAE,CAS9B;AAED,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,23 @@
+/**
+ * Tool aggregator — collects all domain tools into a single list.
+ * The MCP server iterates this list at startup to register handlers
+ * with `@modelcontextprotocol/sdk`.
+ *
+ * @license MIT
+ */
+import { buildElementsTools } from './elements/index.js';
+import { buildHealthTools } from './health.js';
+import { buildInspectionTools } from './inspection.js';
+import { buildPagesTools } from './pages.js';
+import { buildSourcesTools } from './sources/index.js';
+export function buildAllTools(client, options = {}) {
+    const deps = options.elicitation !== undefined ? { elicitation: options.elicitation } : {};
+    return [
+        ...buildHealthTools(client),
+        ...buildPagesTools(client),
+        ...buildElementsTools(client, deps),
+        ...buildSourcesTools(client, deps),
+        ...buildInspectionTools(client),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAcvD,MAAM,UAAU,aAAa,CACzB,MAAkB,EAClB,UAAgC,EAAE;IAElC,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3F,OAAO;QACH,GAAG,gBAAgB,CAAC,MAAM,CAAC;QAC3B,GAAG,eAAe,CAAC,MAAM,CAAC;QAC1B,GAAG,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC;QACnC,GAAG,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC;QAClC,GAAG,oBAAoB,CAAC,MAAM,CAAC;KAClC,CAAC;AACN,CAAC"}

package/dist/tools/inspection.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Element-type inspection tools.
+ *
+ *   yootheme_builder_element_types_list
+ *      → catalogue of available element types (tableResult — Wave G.2)
+ *   yootheme_builder_element_type_get_schema
+ *      → field schema for a single element type (detailResult — Wave G.2)
+ *
+ * @license MIT
+ */
+import type { RestClient } from '../client.js';
+import { type AnyToolDefinition } from './tool-builder.js';
+export declare function buildInspectionTools(client: RestClient): readonly AnyToolDefinition[];
+//# sourceMappingURL=inspection.d.ts.map

package/dist/tools/inspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection.d.ts","sourceRoot":"","sources":["../../src/tools/inspection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAQ/C,OAAO,EAKH,KAAK,iBAAiB,EACzB,MAAM,mBAAmB,CAAC;AAwB3B,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,iBAAiB,EAAE,CA+FrF"}

package/dist/tools/inspection.js

@@ -0,0 +1,115 @@
+/**
+ * Element-type inspection tools.
+ *
+ *   yootheme_builder_element_types_list
+ *      → catalogue of available element types (tableResult — Wave G.2)
+ *   yootheme_builder_element_type_get_schema
+ *      → field schema for a single element type (detailResult — Wave G.2)
+ *
+ * @license MIT
+ */
+import { detailResult, tableResult } from '@getimo/mcp-toolkit';
+import { z } from 'zod';
+import { TYPES_COMPACT_COLUMNS, TYPES_TABLE_COLUMNS, buildTypeSchemaDetail, flattenTypesPayload, mapTypeRow, } from './format/inspection-format.js';
+import { defineTool, errorResult, readOnly, structuredResult, } from './tool-builder.js';
+import { DEFAULT_FIELDS_TYPES_LIST, FIELDS, projectFields, projectedFieldsEcho, } from './sparse-fields.js';
+// ─── outputSchemas (Wave G.2 §4) ─────────────────────────────────────
+const TYPES_LIST_OUTPUT_SCHEMA = z.object({
+    items: z.array(z.record(z.string(), z.unknown())),
+    total: z.number(),
+    projected_fields: z.array(z.string()).optional(),
+});
+const TYPE_SCHEMA_OUTPUT_SCHEMA = z.object({
+    name: z.string(),
+    label: z.string().optional(),
+    origin: z.string().optional(),
+    fields: z.record(z.string(), z.unknown()).optional(),
+    field_count: z.number(),
+});
+export function buildInspectionTools(client) {
+    return [
+        defineTool({
+            name: 'yootheme_builder_element_types_list',
+            description: 'List element types registered on this site (built-ins + ' +
+                'YOOessentials/uEssentials extras). Names feed `element_type` of ' +
+                'element_add. Pass `fields[]` to narrow each row.',
+            inputSchema: {
+                fields: FIELDS,
+            },
+            outputSchema: TYPES_LIST_OUTPUT_SCHEMA,
+            annotations: readOnly('List Element Types'),
+            handler: async ({ fields }) => {
+                try {
+                    const data = await client.get('/element-types');
+                    const flat = flattenTypesPayload(data);
+                    const mapped = flat.map(mapTypeRow);
+                    const mappedRecords = mapped;
+                    const items = projectFields(mappedRecords, fields, DEFAULT_FIELDS_TYPES_LIST);
+                    const echo = projectedFieldsEcho(fields, DEFAULT_FIELDS_TYPES_LIST);
+                    const toolkitResult = tableResult(mappedRecords, {
+                        columns: [...TYPES_TABLE_COLUMNS],
+                        compactColumns: [...TYPES_COMPACT_COLUMNS],
+                        header: (count) => `${String(count)} element types`,
+                        footer: 'Use yootheme_builder_element_type_get_schema <name> for fields.',
+                    });
+                    return structuredResult(toolkitResult, {
+                        items,
+                        total: items.length,
+                        ...(echo !== undefined ? { projected_fields: [...echo] } : {}),
+                    });
+                }
+                catch (e) {
+                    return errorResult({
+                        error: e,
+                        context: {},
+                        hint: 'Run yootheme_builder_diagnose to verify auth.',
+                    });
+                }
+            },
+        }),
+        defineTool({
+            name: 'yootheme_builder_element_type_get_schema',
+            description: 'Get the prop/field schema for a single element type. Use the result to discover ' +
+                'valid keys for `props` when calling yootheme_builder_element_add or ' +
+                '_update_settings.',
+            inputSchema: {
+                type_name: z
+                    .string()
+                    .min(1)
+                    .describe('Element type name (e.g. "headline", "text", "grid"). Use ' +
+                    'yootheme_builder_element_types_list to discover.'),
+            },
+            outputSchema: TYPE_SCHEMA_OUTPUT_SCHEMA,
+            annotations: readOnly('Get Element Type Schema'),
+            handler: async ({ type_name }) => {
+                try {
+                    const data = await client.get(`/element-types/${encodeURIComponent(type_name)}/schema`);
+                    const name = typeof data.name === 'string' ? data.name : type_name;
+                    const label = typeof data.label === 'string' ? data.label : undefined;
+                    const origin = typeof data.origin === 'string' ? data.origin : undefined;
+                    const fields = data.fields !== null && typeof data.fields === 'object'
+                        ? data.fields
+                        : undefined;
+                    const fieldCount = fields !== undefined ? Object.keys(fields).length : 0;
+                    const toolkitResult = detailResult(buildTypeSchemaDetail({ name, label, origin, fields }));
+                    return structuredResult(toolkitResult, {
+                        name,
+                        ...(label !== undefined ? { label } : {}),
+                        ...(origin !== undefined ? { origin } : {}),
+                        ...(fields !== undefined ? { fields } : {}),
+                        field_count: fieldCount,
+                    });
+                }
+                catch (e) {
+                    return errorResult({
+                        error: e,
+                        context: { type_name },
+                        hint: 'Verify type_name via yootheme_builder_element_types_list — names ' +
+                            'are case-sensitive.',
+                    });
+                }
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=inspection.js.map

package/dist/tools/inspection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection.js","sourceRoot":"","sources":["../../src/tools/inspection.ts"],"names":[],"mappings":"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"}

package/dist/tools/layout-flatten.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Layout-flatten helper — depth-first walk that turns a nested YOOtheme
+ * layout tree into a flat array of `{ path, parent_path, depth,
+ * element_type, props }` records.
+ *
+ * Used by `yootheme_builder_page_get_layout` when called with
+ * `flat: true`. Per Design §4.4.1:
+ *
+ *   - Walk-order: depth-first, parent BEFORE children, original child
+ *     order preserved (no sort).
+ *   - `path` uses JSON-Pointer-style notation rooted at `/layout/<key>`
+ *     and descends via `/children/<index>` segments. The root segments
+ *     mirror the keys the REST plugin produces (string keys "0","1",…
+ *     when the top-level layout is an object; numeric indices when it
+ *     happens to be an array).
+ *   - `parent_path` is `null` for top-level entries.
+ *   - The emitted record's `children` field is REMOVED — children become
+ *     their own emitted entries with their own `path`. Keeping the nested
+ *     array would defeat the purpose of flattening.
+ *   - Non-object children are skipped silently but their index is
+ *     preserved in the parent's child-numbering (the next valid sibling
+ *     keeps its original index).
+ *
+ * Pure function — no I/O, no client dependency. Test-covered in
+ * `tests/tools/layout-flatten.test.ts`.
+ *
+ * @license MIT
+ */
+/** A single emitted record in the flattened layout. */
+export interface FlatElement {
+    /** JSON-Pointer-style path, e.g. "/layout/0/children/2". */
+    path: string;
+    /** Path of the parent element, or `null` for top-level entries. */
+    parent_path: string | null;
+    /** 0-based depth (top-level entries have depth 0). */
+    depth: number;
+    /** Element type string (the `type` field on the YT node, "" if missing). */
+    element_type: string;
+    /** Element props (passthrough; `undefined` when the node has none). */
+    props?: Record<string, unknown>;
+    /**
+     * Children intentionally absent — see file-header. Kept in the type
+     * so consumers can confirm the field is `undefined` rather than
+     * assume it exists.
+     */
+    children?: undefined;
+    /**
+     * Allow passthrough of any other top-level fields the REST plugin
+     * may add in future (e.g. `label`, `has_binding`, `name`). The
+     * walker preserves these verbatim so projection via `pickFields`
+     * downstream stays meaningful.
+     */
+    [extra: string]: unknown;
+}
+/**
+ * Flatten a YOOtheme nested layout tree.
+ *
+ * @param layout - The top-level layout container. Accepts either an
+ *   object keyed by stringified indices ("0","1",…) or an actual array.
+ *   Returns `[]` for empty input or anything that isn't iterable.
+ */
+export declare function flattenLayout(layout: unknown): FlatElement[];
+//# sourceMappingURL=layout-flatten.d.ts.map

package/dist/tools/layout-flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-flatten.d.ts","sourceRoot":"","sources":["../../src/tools/layout-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uDAAuD;AACvD,MAAM,WAAW,WAAW;IACxB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;OAKG;IACH,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,EAAE,CAmB5D"}