handoff-app 1.2.2-6 → 2.0.0-0

package/dist/nav/index.d.ts

@@ -0,0 +1,83 @@
+/** A mode-aware placeholder retained in the serialized navigation shell. */
+export interface NavDynamicSlot {
+    kind: 'components' | 'patterns' | 'token-components';
+    type?: string;
+}
+/** A link nested within a navigation subsection. */
+export interface NavMenuItem {
+    title: string;
+    path?: string;
+    image?: string;
+    menu?: NavMenuItem[];
+}
+/** A group or direct link beneath a top-level navigation section. */
+export interface NavSubSection {
+    title: string;
+    path?: string;
+    image?: string;
+    menu?: NavMenuItem[];
+    dynamic?: NavDynamicSlot;
+}
+/** The canonical top-level navigation section shared by the build pipeline and docs app. */
+export interface SectionLink {
+    title: string;
+    weight: number;
+    external?: string | boolean;
+    path: string;
+    subSections: NavSubSection[];
+}
+/** Minimal navigation entity served by the docs navigation endpoint. */
+export interface NavEntity {
+    id: string;
+    title?: string;
+    group?: string;
+    type?: string;
+}
+/** A navigation token-set record. Only component sets are rendered in the component-token slot. */
+export interface NavTokenSet extends NavEntity {
+    kind: 'foundation' | 'component';
+}
+/** A declarative submenu entry carried by a page record. */
+export interface NavPageMenuDeclaration {
+    title?: string;
+    enabled?: boolean;
+    components?: boolean | string;
+    patterns?: boolean;
+    tokens?: boolean;
+    path?: string;
+    image?: string;
+    menu?: NavMenuItem[];
+}
+/** The page fields needed to compose page-authored navigation sections. */
+export interface NavPageRecord {
+    id: string;
+    path?: string;
+    title?: string;
+    menuTitle?: string;
+    weight?: number;
+    enabled?: boolean;
+    external?: string | boolean;
+    menu?: Record<string, NavPageMenuDeclaration> | NavPageMenuDeclaration[];
+}
+/** Eager, already-resolved inputs to the pure navigation resolver. */
+export interface NavSources {
+    shell: SectionLink[];
+    components: NavEntity[];
+    patterns: NavEntity[];
+    pages: NavPageRecord[];
+    tokenSets: NavTokenSet[];
+    tokenFoundations: NavMenuItem[];
+    basePath?: string;
+}
+export type NavMode = 'workspace' | 'registry';
+export type NavLoad = 'initial' | 'refresh';
+/** The render-ready navigation payload. */
+export interface NavData {
+    shell: SectionLink[];
+}
+export { getNavData } from './resolver';
+export type { GetNavDataInput } from './resolver';
+export { getWorkspaceNavData } from './workspace';
+export type { WorkspaceNavAdapterOptions, WorkspaceNavLoaders } from './workspace';
+export { getRegistryNavData } from './registry';
+export type { RegistryNavAdapterOptions, RegistryNavRecords } from './registry';

package/dist/nav/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRegistryNavData = exports.getWorkspaceNavData = exports.getNavData = void 0;
+var resolver_1 = require("./resolver");
+Object.defineProperty(exports, "getNavData", { enumerable: true, get: function () { return resolver_1.getNavData; } });
+var workspace_1 = require("./workspace");
+Object.defineProperty(exports, "getWorkspaceNavData", { enumerable: true, get: function () { return workspace_1.getWorkspaceNavData; } });
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "getRegistryNavData", { enumerable: true, get: function () { return registry_1.getRegistryNavData; } });

package/dist/nav/registry.d.ts

@@ -0,0 +1,15 @@
+import type { NavData, NavEntity, NavLoad, NavPageRecord, NavTokenSet, SectionLink } from '.';
+export interface RegistryNavRecords {
+    components: NavEntity[];
+    patterns: NavEntity[];
+    pages: NavPageRecord[];
+    tokenSets: NavTokenSet[];
+}
+export interface RegistryNavAdapterOptions {
+    shell: SectionLink[];
+    load: NavLoad;
+    basePath?: string;
+    fetchRecords: () => Promise<RegistryNavRecords>;
+}
+/** Registry adapter: shell-only initial load, or one best-effort runtime-record fetch on refresh. */
+export declare const getRegistryNavData: (options: RegistryNavAdapterOptions) => Promise<NavData>;

package/dist/nav/registry.js

@@ -0,0 +1,42 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRegistryNavData = void 0;
+const menu_shell_1 = require("../utils/menu-shell");
+const resolver_1 = require("./resolver");
+const emptyRecords = () => ({ components: [], patterns: [], pages: [], tokenSets: [] });
+/** Registry adapter: shell-only initial load, or one best-effort runtime-record fetch on refresh. */
+const getRegistryNavData = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    let records = emptyRecords();
+    if (options.load === 'refresh') {
+        try {
+            records = (_a = (yield options.fetchRecords())) !== null && _a !== void 0 ? _a : records;
+        }
+        catch (_b) {
+            // Fall back to the baked navigation shell when the registry backend is unavailable.
+        }
+    }
+    const componentById = new Map(records.components.map((component) => [component.id, component]));
+    const tokenSets = records.tokenSets.map((set) => {
+        var _a;
+        const id = set.id.startsWith('component/') ? set.id.slice('component/'.length) : set.id;
+        const component = componentById.get(id);
+        return Object.assign(Object.assign({}, set), { title: set.title || (component === null || component === void 0 ? void 0 : component.title), group: (_a = set.group) !== null && _a !== void 0 ? _a : component === null || component === void 0 ? void 0 : component.group });
+    });
+    const normalizedBasePath = options.basePath ? `${options.basePath.replace(/^\/+|\/+$/g, '')}/` : '';
+    return (0, resolver_1.getNavData)({
+        mode: 'registry',
+        load: options.load,
+        sources: Object.assign(Object.assign({ shell: options.shell }, records), { tokenSets, tokenFoundations: (0, menu_shell_1.buildTokensFoundationsMenu)(normalizedBasePath), basePath: options.basePath }),
+    });
+});
+exports.getRegistryNavData = getRegistryNavData;

package/dist/nav/resolver.d.ts

@@ -0,0 +1,8 @@
+import type { NavData, NavLoad, NavMode, NavSources } from '.';
+export interface GetNavDataInput {
+    mode: NavMode;
+    load: NavLoad;
+    sources: NavSources;
+}
+/** Resolve an eager navigation snapshot without fetching, mutation, or asynchronous work. */
+export declare const getNavData: ({ mode, load, sources }: GetNavDataInput) => NavData;

package/dist/nav/resolver.js

@@ -0,0 +1,192 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNavData = void 0;
+const lodash_1 = require("lodash");
+const normalizeBasePath = (basePath) => {
+    if (!basePath)
+        return '';
+    return `${basePath.replace(/^\/+|\/+$/g, '')}/`;
+};
+const cloneMenu = (menu = []) => menu.map((item) => (Object.assign(Object.assign({}, item), (item.menu ? { menu: cloneMenu(item.menu) } : {}))));
+const cloneSubSection = (section) => (Object.assign(Object.assign(Object.assign({}, section), (section.dynamic ? { dynamic: Object.assign({}, section.dynamic) } : {})), (section.menu ? { menu: cloneMenu(section.menu) } : {})));
+const cloneSection = (section) => (Object.assign(Object.assign({}, section), { subSections: section.subSections.map(cloneSubSection) }));
+const entityTitle = (entity) => entity.title || (0, lodash_1.startCase)(entity.id);
+const buildEntityMenu = (entities, segment, basePath) => {
+    var _a, _b;
+    const grouped = new Map();
+    for (const entity of entities) {
+        const group = (_a = entity.group) !== null && _a !== void 0 ? _a : '';
+        grouped.set(group, [...((_b = grouped.get(group)) !== null && _b !== void 0 ? _b : []), entity]);
+    }
+    return Array.from(grouped.entries())
+        .map(([group, records]) => ({
+        title: group || 'Uncategorized',
+        path: '',
+        menu: records
+            .map((record) => ({
+            title: entityTitle(record),
+            path: `${basePath}system/${segment}/${record.id}`,
+        }))
+            .sort((a, b) => a.title.localeCompare(b.title)),
+    }))
+        .map((_a) => {
+        var { path: _path } = _a, group = __rest(_a, ["path"]);
+        return group;
+    })
+        .sort((a, b) => a.title.localeCompare(b.title));
+};
+const buildTokensMenu = (sources, basePath) => {
+    const foundations = cloneMenu(sources.tokenFoundations);
+    const componentSets = sources.tokenSets
+        .filter((set) => set.kind === 'component')
+        .map((set) => {
+        const id = set.id.startsWith('component/') ? set.id.slice('component/'.length) : set.id;
+        return {
+            title: set.title || (0, lodash_1.startCase)(id),
+            path: `${basePath}system/tokens/components/${id}`,
+        };
+    })
+        .sort((a, b) => a.title.localeCompare(b.title));
+    if (componentSets.length > 0) {
+        foundations.push({
+            title: 'Components',
+            path: `${basePath}system/tokens/components`,
+            menu: componentSets,
+        });
+    }
+    return foundations;
+};
+const fillSubSections = (subSections, sources, keepEmpty) => {
+    var _a, _b, _c, _d, _e;
+    const basePath = normalizeBasePath(sources.basePath);
+    const resolved = [];
+    for (const original of subSections) {
+        const section = cloneSubSection(original);
+        if (((_a = section.dynamic) === null || _a === void 0 ? void 0 : _a.kind) === 'components') {
+            const entities = section.dynamic.type
+                ? sources.components.filter((component) => { var _a; return component.type === ((_a = section.dynamic) === null || _a === void 0 ? void 0 : _a.type); })
+                : sources.components;
+            section.menu = buildEntityMenu(entities, 'component', basePath);
+        }
+        else if (((_b = section.dynamic) === null || _b === void 0 ? void 0 : _b.kind) === 'patterns') {
+            section.menu = buildEntityMenu(sources.patterns, 'pattern', basePath);
+        }
+        else if (((_c = section.dynamic) === null || _c === void 0 ? void 0 : _c.kind) === 'token-components') {
+            section.menu = buildTokensMenu(sources, basePath);
+        }
+        if (!section.dynamic || keepEmpty || ((_e = (_d = section.menu) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0) > 0) {
+            resolved.push(section);
+        }
+    }
+    return resolved;
+};
+const pageMenuEntries = (menu) => (Array.isArray(menu) ? menu : Object.values(menu !== null && menu !== void 0 ? menu : {}));
+const declarationToSubSection = (declaration, sources) => {
+    var _a, _b, _c;
+    if (declaration.components) {
+        return {
+            title: (_a = declaration.title) !== null && _a !== void 0 ? _a : 'Components',
+            menu: [],
+            dynamic: typeof declaration.components === 'string' ? { kind: 'components', type: declaration.components } : { kind: 'components' },
+        };
+    }
+    if (declaration.patterns) {
+        return { title: (_b = declaration.title) !== null && _b !== void 0 ? _b : 'Patterns', menu: [], dynamic: { kind: 'patterns' } };
+    }
+    if (declaration.tokens) {
+        return {
+            title: 'Tokens',
+            menu: cloneMenu(sources.tokenFoundations),
+            dynamic: { kind: 'token-components' },
+        };
+    }
+    if (declaration.enabled === false)
+        return undefined;
+    return Object.assign(Object.assign(Object.assign({ title: (_c = declaration.title) !== null && _c !== void 0 ? _c : '' }, (declaration.path !== undefined ? { path: declaration.path } : {})), (declaration.image !== undefined ? { image: declaration.image } : {})), (declaration.menu !== undefined ? { menu: cloneMenu(declaration.menu) } : {}));
+};
+const buildChildPageItems = (parentId, pages) => {
+    const prefix = `${parentId}/`;
+    const segments = Array.from(new Set(pages.filter((page) => page.id.startsWith(prefix)).map((page) => page.id.slice(prefix.length).split('/')[0])));
+    return segments
+        .map((segment) => {
+        var _a, _b;
+        const id = `${parentId}/${segment}`;
+        const record = pages.find((page) => page.id === id);
+        const nested = buildChildPageItems(id, pages);
+        const item = {
+            title: (record === null || record === void 0 ? void 0 : record.menuTitle) || (record === null || record === void 0 ? void 0 : record.title) || (0, lodash_1.startCase)(segment),
+            path: (_a = record === null || record === void 0 ? void 0 : record.path) !== null && _a !== void 0 ? _a : `/${id}`,
+            weight: (_b = record === null || record === void 0 ? void 0 : record.weight) !== null && _b !== void 0 ? _b : 0,
+        };
+        if (nested.length > 0)
+            item.menu = nested;
+        return item;
+    })
+        .sort((a, b) => a.weight - b.weight || a.title.localeCompare(b.title))
+        .map((_a) => {
+        var { weight: _weight } = _a, item = __rest(_a, ["weight"]);
+        return item;
+    });
+};
+const buildPageSections = (sources, keepEmpty) => {
+    const pages = sources.pages.filter((page) => page.enabled !== false);
+    return pages
+        .filter((page) => !page.id.includes('/'))
+        .map((page) => {
+        var _a, _b;
+        const declared = page.menu
+            ? pageMenuEntries(page.menu)
+                .map((entry) => declarationToSubSection(entry, sources))
+                .filter((entry) => entry !== undefined)
+            : [];
+        const children = page.menu ? [] : buildChildPageItems(page.id, pages);
+        const subSections = page.menu
+            ? fillSubSections(declared, sources, keepEmpty)
+            : children.length > 0
+                ? [{ title: page.menuTitle || page.title || (0, lodash_1.startCase)(page.id), menu: children }]
+                : [];
+        const external = typeof page.external === 'string' &&
+            (page.external.startsWith('http://') || page.external.startsWith('https://') || page.external.startsWith('/'))
+            ? page.external
+            : false;
+        return {
+            title: page.menuTitle || page.title || (0, lodash_1.startCase)(page.id),
+            external,
+            weight: (_a = page.weight) !== null && _a !== void 0 ? _a : 0,
+            path: (_b = page.path) !== null && _b !== void 0 ? _b : `/${page.id}`,
+            subSections,
+        };
+    });
+};
+const resolveCompleteTree = (sources, keepEmpty) => {
+    const byPath = new Map(sources.shell.map((section) => [
+        section.path,
+        Object.assign(Object.assign({}, cloneSection(section)), { subSections: fillSubSections(section.subSections, sources, keepEmpty) }),
+    ]));
+    for (const section of buildPageSections(sources, keepEmpty)) {
+        byPath.set(section.path, section);
+    }
+    return Array.from(byPath.values()).sort((a, b) => a.weight - b.weight);
+};
+/** Resolve an eager navigation snapshot without fetching, mutation, or asynchronous work. */
+const getNavData = ({ mode, load, sources }) => {
+    if (mode === 'workspace') {
+        return { shell: resolveCompleteTree(sources, false) };
+    }
+    if (load === 'initial') {
+        return { shell: sources.shell.map(cloneSection) };
+    }
+    return { shell: resolveCompleteTree(sources, true) };
+};
+exports.getNavData = getNavData;

package/dist/nav/workspace.d.ts

@@ -0,0 +1,18 @@
+import type { NavData, NavEntity, NavLoad, NavPageRecord, NavTokenSet } from '.';
+type Awaitable<T> = T | Promise<T>;
+export interface WorkspaceNavLoaders {
+    components: () => Awaitable<NavEntity[]>;
+    patterns: () => Awaitable<NavEntity[]>;
+    pages: () => Awaitable<NavPageRecord[]>;
+    tokenSets: () => Awaitable<NavTokenSet[]>;
+}
+export interface WorkspaceNavAdapterOptions {
+    docRoot: string;
+    workingPagesDir?: string;
+    basePath?: string;
+    load?: NavLoad;
+    loaders: WorkspaceNavLoaders;
+}
+/** Workspace/static adapter: live filesystem shell plus best-effort local snapshot loaders. */
+export declare const getWorkspaceNavData: (options: WorkspaceNavAdapterOptions) => Promise<NavData>;
+export {};

package/dist/nav/workspace.js

@@ -0,0 +1,103 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWorkspaceNavData = void 0;
+const fs = __importStar(require("fs"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const path_1 = __importDefault(require("path"));
+const menu_shell_1 = require("../utils/menu-shell");
+const resolver_1 = require("./resolver");
+const safeLoad = (load) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    try {
+        return (_a = (yield load())) !== null && _a !== void 0 ? _a : [];
+    }
+    catch (_b) {
+        return [];
+    }
+});
+const markdownTitle = (id, docRoot, workingPagesDir) => {
+    const candidates = [
+        workingPagesDir ? path_1.default.resolve(workingPagesDir, 'system', `${id}.md`) : '',
+        path_1.default.resolve(docRoot, 'system', `${id}.md`),
+    ];
+    for (const candidate of candidates) {
+        if (!candidate || !fs.existsSync(candidate))
+            continue;
+        const title = (0, gray_matter_1.default)(fs.readFileSync(candidate, 'utf8')).data.title;
+        if (typeof title === 'string' && title.trim())
+            return title;
+    }
+    return undefined;
+};
+/** Workspace/static adapter: live filesystem shell plus best-effort local snapshot loaders. */
+const getWorkspaceNavData = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const [loadedComponents, patterns, pages, loadedTokenSets] = yield Promise.all([
+        safeLoad(options.loaders.components),
+        safeLoad(options.loaders.patterns),
+        safeLoad(options.loaders.pages),
+        safeLoad(options.loaders.tokenSets),
+    ]);
+    const components = loadedComponents.map((component) => (Object.assign(Object.assign({}, component), { title: component.title || markdownTitle(component.id, options.docRoot, options.workingPagesDir) })));
+    const componentById = new Map(components.map((component) => [component.id, component]));
+    const tokenSets = loadedTokenSets.map((set) => {
+        var _a;
+        const id = set.id.startsWith('component/') ? set.id.slice('component/'.length) : set.id;
+        const component = componentById.get(id);
+        return Object.assign(Object.assign({}, set), { title: set.title || (component === null || component === void 0 ? void 0 : component.title) || markdownTitle(id, options.docRoot, options.workingPagesDir), group: (_a = set.group) !== null && _a !== void 0 ? _a : component === null || component === void 0 ? void 0 : component.group });
+    });
+    const normalizedBasePath = options.basePath ? `${options.basePath.replace(/^\/+|\/+$/g, '')}/` : '';
+    return (0, resolver_1.getNavData)({
+        mode: 'workspace',
+        load: (_a = options.load) !== null && _a !== void 0 ? _a : 'refresh',
+        sources: {
+            shell: (0, menu_shell_1.buildMenuShell)({
+                docRoot: options.docRoot,
+                workingPagesDir: options.workingPagesDir,
+                basePath: options.basePath,
+            }),
+            components,
+            patterns,
+            pages,
+            tokenSets,
+            tokenFoundations: (0, menu_shell_1.buildTokensFoundationsMenu)(normalizedBasePath),
+            basePath: options.basePath,
+        },
+    });
+});
+exports.getWorkspaceNavData = getWorkspaceNavData;

package/dist/pipeline/styles.js

@@ -18,6 +18,7 @@ const handoff_core_1 = require("handoff-core");
 const lodash_1 = require("lodash");
 const path_1 = __importDefault(require("path"));
 const archive_1 = require("./archive");
+const token_transformers_1 = require("./token-transformers");
 /**
  * Build just the custom fonts — zips font directories and copies them to the export folder.
  */
@@ -49,39 +50,10 @@ exports.buildCustomFonts = buildCustomFonts;
  * Builds design token style files using core and user-configured transformers.
  */
 const buildStyles = (handoff, documentationObject) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d;
-    // Core transformers that should always be included
-    const coreTransformers = [
-        {
-            transformer: handoff_core_1.Transformers.ScssTransformer,
-            outDir: 'sass',
-            format: 'scss',
-        },
-        {
-            transformer: handoff_core_1.Transformers.ScssTypesTransformer,
-            outDir: 'types',
-            format: 'scss',
-        },
-        {
-            transformer: handoff_core_1.Transformers.CssTransformer,
-            outDir: 'css',
-            format: 'css',
-        },
-    ];
-    // Get user-configured transformers
-    const userTransformers = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.pipeline) === null || _b === void 0 ? void 0 : _b.transformers) || [];
-    // Merge core transformers with user transformers
-    // If a user transformer matches a core transformer, use user's outDir and format
-    const transformers = coreTransformers.map((coreTransformer) => {
-        const userTransformer = userTransformers.find((t) => t.transformer === coreTransformer.transformer);
-        return userTransformer ? Object.assign(Object.assign({}, coreTransformer), { outDir: userTransformer.outDir, format: userTransformer.format }) : coreTransformer;
-    });
-    // Add any additional user transformers that aren't core transformers
-    userTransformers.forEach((userTransformer) => {
-        if (!coreTransformers.some((core) => core.transformer === userTransformer.transformer)) {
-            transformers.push(userTransformer);
-        }
-    });
+    var _a, _b;
+    // Resolve the merged core + user-configured transformer list (single source of truth, shared with
+    // the registry publish packaging so the on-disk layout never drifts).
+    const transformers = (0, token_transformers_1.resolveTokenTransformers)(handoff);
     const baseDir = handoff.getVariablesFilePath();
     const runner = yield handoff.getRunner();
     // Create transformer instances and transform documentation object
@@ -100,7 +72,7 @@ const buildStyles = (handoff, documentationObject) => __awaiter(void 0, void 0,
     // Special case for SD tokens components directory
     const sdTransformer = transformers.find((t) => t.transformer === handoff_core_1.Transformers.StyleDictionaryTransformer);
     if (sdTransformer) {
-        const sdFiles = (_c = transformedFiles.find((t) => t.transformer === handoff_core_1.Transformers.StyleDictionaryTransformer)) === null || _c === void 0 ? void 0 : _c.files;
+        const sdFiles = (_a = transformedFiles.find((t) => t.transformer === handoff_core_1.Transformers.StyleDictionaryTransformer)) === null || _a === void 0 ? void 0 : _a.files;
         if (sdFiles === null || sdFiles === void 0 ? void 0 : sdFiles.components) {
             yield Promise.all(Object.keys(sdFiles.components).map((name) => fs_extra_1.default.ensureDir(path_1.default.join(baseDir, sdTransformer.outDir, name))));
         }
@@ -125,7 +97,7 @@ const buildStyles = (handoff, documentationObject) => __awaiter(void 0, void 0,
         return [...componentPromises, ...designPromises];
     });
     // Generate tokens-map.json
-    const mapFiles = (_d = transformedFiles.find((t) => t.transformer === handoff_core_1.Transformers.MapTransformer)) === null || _d === void 0 ? void 0 : _d.files;
+    const mapFiles = (_b = transformedFiles.find((t) => t.transformer === handoff_core_1.Transformers.MapTransformer)) === null || _b === void 0 ? void 0 : _b.files;
     if (mapFiles) {
         const tokensMapContent = JSON.stringify(Object.entries(mapFiles.components || {}).reduce((acc, [_, data]) => (Object.assign(Object.assign({}, acc), JSON.parse(data))), Object.assign(Object.assign(Object.assign({}, JSON.parse(mapFiles.design.colors)), JSON.parse(mapFiles.design.typography)), JSON.parse(mapFiles.design.effects))), null, 2);
         writePromises.push(fs_extra_1.default.writeFile(path_1.default.join(handoff.getOutputPath(), 'tokens-map.json'), tokensMapContent));

package/dist/pipeline/token-transformers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared resolution of the design-token style transformers and their on-disk layout.
+ *
+ * Both {@link import('./styles').buildStyles} (which writes the generated token files) and the
+ * registry publish packaging (which reads them back byte-for-byte) must agree on exactly which
+ * transformers run, their output directories/formats, and the path each set's files land at. This
+ * module is the single source of that layout so the two never drift.
+ */
+import type { TransformerConfig } from '../types/config';
+/** Minimal shape needed to resolve transformers: just the pipeline transformer config. */
+export interface TokenTransformerContext {
+    config?: {
+        pipeline?: {
+            transformers?: TransformerConfig[];
+        } | null;
+    } | null;
+}
+/** A resolved token transformer: the factory plus its output directory, file format, and logical label. */
+export interface ResolvedTokenTransformer {
+    transformer: any;
+    outDir: string;
+    format: string;
+    /** Stable logical label for the output (`css`|`scss`|`types`|`styleDictionary`|custom `outDir`). */
+    label: string;
+}
+/**
+ * Resolve the merged transformer list (core + user-configured). A user transformer matching a core
+ * transformer overrides its `outDir`/`format`; other user transformers (e.g. Style Dictionary or a
+ * fully custom transformer) are appended. Mirrors the historical inline logic in `buildStyles`.
+ */
+export declare const resolveTokenTransformers: (context: TokenTransformerContext) => ResolvedTokenTransformer[];
+/** A generated token artifact expected for a set: its registry-safe relative path + logical label. */
+export interface TokenArtifactLayout {
+    /** Path relative to `getVariablesFilePath()`, e.g. `css/colors.css` or `sd/button/button.tokens.json`. */
+    path: string;
+    /** Logical format label (`css`|`scss`|`types`|`styleDictionary`|custom). */
+    format: string;
+}
+/**
+ * Compute the registry-safe relative paths (under `getVariablesFilePath()`) a single set's generated
+ * files land at, across every resolved transformer. Honors the Style Dictionary nesting special-case
+ * (`buildStyles`): SD component tokens go to `<outDir>/<name>/<name>.tokens.json`, SD foundation
+ * tokens to `<outDir>/<name>.tokens.json`; every other transformer writes `<outDir>/<name>.<format>`.
+ */
+export declare const tokenArtifactPathsForSet: (transformers: ResolvedTokenTransformer[], setName: string, isComponent: boolean) => TokenArtifactLayout[];