@scaffold-ui-kit/preview 0.0.0-stage → 2.3.0

package/dist/context.js

@@ -0,0 +1,783 @@
+// Load and validate the kit configuration's `preview` block. The build leaves
+// the block alone - this package owns it: the kit configuration is found and
+// read by scaffold-ui-kit's own resolver (`scaffold-ui-kit.ts` or
+// `scaffold-ui-kit.json`), and the block is validated by hand (the errors
+// name the offending key) and resolved into absolute paths. Kit-authored TS
+// modules (templates, story files, manual specs, views) are imported through
+// jiti, so the built CLI compiles them on the fly as the build compiles
+// templates.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { createJiti } from 'jiti';
+import { ALL_TARGETS, PREVIEW_BROWSER_KEYS, } from './lib/types.js';
+import { isPaneWidth, MAXIMUM_PANE_WIDTH } from './controller/persistence.js';
+function fail(message) {
+    throw new Error(`[preview] ${message}`);
+}
+/** The keys the `preview` block takes. */
+const PREVIEW_KEYS = [
+    'shell',
+    'sources',
+    'options',
+    'canvas',
+    'themes',
+    'mount',
+    'viewCanvas',
+    'paneWidths',
+    'controlHints',
+    'labels',
+    'viewsModule',
+    'codeBlock',
+    'setupModules',
+    'htmlStylesheets',
+    'aliases',
+    'scssLoadPaths',
+    'optimizeDepsExclude',
+    'dedupe',
+    'omitPattern',
+    'handWrittenComponents',
+    'port',
+    'host',
+    'persistence',
+    'landing',
+];
+/** The keys a `preview.sources` entry takes. */
+const SOURCE_KEYS = [
+    'id',
+    'label',
+    'order',
+    'moduleBase',
+    'templatesDirectory',
+    'manualModule',
+    'storiesDirectory',
+];
+/** The keys `preview.codeBlock` takes. */
+const CODE_BLOCK_KEYS = [
+    'module',
+    'framework',
+];
+/** The keys `preview.landing` takes. */
+const LANDING_KEYS = ['view', 'component', 'scenario'];
+/** The keys the object form of a `handWrittenComponents` entry takes. */
+const HAND_WRITTEN_KEYS = [
+    'template',
+    'slots',
+];
+/** What to write for a key the `preview` block does not take, where one thing is meant. */
+const PREVIEW_KEY_REPLACEMENTS = new Map([
+    ['scopes', "'sources'"],
+    [
+        'configurationModule',
+        "the keys of the 'preview' block, such as options, canvas, themes and mount",
+    ],
+]);
+/** What to write for a key a `preview.sources` entry does not take, where one thing is meant. */
+const SOURCE_KEY_REPLACEMENTS = new Map([
+    ['sidecarsDirectory', "'storiesDirectory'"],
+]);
+/** Whether a value is a plain object, whose keys can be checked. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Each key of an object that is not among the keys it takes, with its path
+ * and the keys the object takes, as the scaffolder reports the
+ * configuration's own keys, or what to use instead where `replacements`
+ * names it.
+ */
+function unknownKeyProblems(value, allowed, path, description, replacements = new Map()) {
+    return Object.keys(value)
+        .filter((key) => !allowed.includes(key))
+        .map((key) => {
+        const replacement = replacements.get(key);
+        return `unknown key '${path}.${key}'; ${replacement === undefined
+            ? `${description} takes ${allowed.join(', ')}`
+            : `use ${replacement}`}`;
+    });
+}
+/**
+ * What is wrong with a list of pane widths, or nothing: it must be a list of
+ * `{ label, width }`, each label a non-empty string and each width a whole
+ * number of CSS pixels from 1 to the most a pane is laid out at, no label
+ * and no width named twice.
+ *
+ * @param paneWidths - The list, as the kit gives it.
+ * @param name - Where the kit gives it, for the message.
+ * @returns The problem, or `undefined` when the list is sound.
+ * @example
+ * ```ts
+ * paneWidthsProblem([{ label: 'small', width: 375 }], 'paneWidths'); // undefined
+ * ```
+ */
+export function paneWidthsProblem(paneWidths, name) {
+    if (!Array.isArray(paneWidths) ||
+        paneWidths.some((paneWidth) => !isPlainObject(paneWidth) ||
+            typeof paneWidth.label !== 'string' ||
+            paneWidth.label.trim() === '' ||
+            !isPaneWidth(paneWidth.width)))
+        return `${name} must be a list of { label, width }: a label to pick it by, and a width in CSS pixels, a whole number from 1 to ${MAXIMUM_PANE_WIDTH}`;
+    const widths = paneWidths;
+    if (new Set(widths.map((paneWidth) => paneWidth.label)).size !== widths.length)
+        return `${name} must not name a label twice`;
+    if (new Set(widths.map((paneWidth) => paneWidth.width)).size !== widths.length)
+        return `${name} must not name a width twice`;
+    return undefined;
+}
+/** What is wrong with the shape of `preview.landing`, or nothing. */
+function landingShapeProblem(landing) {
+    const shape = "preview.landing must be { view } or { component, scenario? }: a view's id, or a story's id and, if it is not to open on its baseline, a scenario's, as the preview's address names them";
+    if (!isPlainObject(landing))
+        return shape;
+    const candidate = landing;
+    const named = (key) => typeof candidate[key] === 'string' && candidate[key] !== '';
+    if ('view' in candidate) {
+        if (!named('view') || 'component' in candidate || 'scenario' in candidate)
+            return shape;
+        return undefined;
+    }
+    if (!named('component'))
+        return shape;
+    if ('scenario' in candidate && !named('scenario'))
+        return shape;
+    return undefined;
+}
+function validateSource(source, index) {
+    const candidate = source;
+    if (!candidate || typeof candidate !== 'object')
+        fail(`preview.sources[${index}] must be an object`);
+    for (const key of ['id', 'label', 'moduleBase']) {
+        if (typeof candidate[key] !== 'string' || !candidate[key]) {
+            fail(`preview.sources[${index}].${key} must be a non-empty string`);
+        }
+    }
+    if (typeof candidate.order !== 'number')
+        fail(`preview.sources[${index}].order must be a number`);
+    return candidate;
+}
+/**
+ * What is wrong with a `preview.shell` that is set, or `undefined` when it
+ * is a specifier or a `{ module, page }` of specifiers.
+ */
+function shellSettingProblem(setting) {
+    if (typeof setting === 'string')
+        return undefined;
+    const shape = "preview.shell must be a package specifier or a module path, or an object with 'module' and optional 'page'";
+    if (typeof setting !== 'object' || setting === null || Array.isArray(setting))
+        return shape;
+    const { module, page, ...rest } = setting;
+    const unknown = Object.keys(rest);
+    if (unknown.length > 0)
+        return `unknown key 'preview.shell.${unknown[0]}'; preview.shell takes module and page`;
+    if (typeof module !== 'string' || !module)
+        return "preview.shell.module is required: the shell's module, as a package specifier or a module path relative to the kit root";
+    if (page !== undefined && (typeof page !== 'string' || !page))
+        return "preview.shell.page must be a package specifier or a module path relative to the kit root: the shell's page module";
+    return undefined;
+}
+/** The shell shipped with the preview, named when a kit configures none. */
+export const CHARCELL_SHELL = '@scaffold-ui-kit/preview/shells/charcell';
+/**
+ * Where `preview.shell` points: a module in the kit when it is
+ * written as a path (relative, absolute, or one that exists under the kit
+ * root, like the other module settings), else a package resolved from the
+ * kit's root the way the kit's own imports are.
+ */
+function resolveShellModule(kitRoot, shell) {
+    if (isModulePath(kitRoot, shell)) {
+        const inKit = resolve(kitRoot, shell);
+        if (!existsSync(inKit)) {
+            fail(`preview.shell names a module that does not exist: ${inKit}`);
+        }
+        return inKit;
+    }
+    try {
+        return createRequire(resolve(kitRoot, 'package.json')).resolve(shell);
+    }
+    catch {
+        return fail(`preview.shell '${shell}' is neither a module in the kit nor a package installed in it (resolved from ${kitRoot}). ` +
+            `Install the package the shell comes from, or give a path relative to the kit root. ` +
+            `The shell shipped with the preview is '${CHARCELL_SHELL}'; it needs charcell and @zag-js/react installed.`);
+    }
+}
+/** Whether a module setting is written as a path: relative, absolute, or
+ *  one that exists under the kit root. Anything else is a package specifier. */
+function isModulePath(kitRoot, setting) {
+    return (setting.startsWith('.') ||
+        isAbsolute(setting) ||
+        existsSync(resolve(kitRoot, setting)));
+}
+/**
+ * Whether the package a specifier names lists `<specifier>/<subpath>` among
+ * its exports, read from its `package.json`; `false` when the package or its
+ * exports cannot be read.
+ */
+function packageExports(fromKit, specifier, subpath) {
+    const [scopeOrName, name] = specifier.split('/');
+    const packageName = specifier.startsWith('@')
+        ? `${scopeOrName}/${name}`
+        : scopeOrName;
+    try {
+        const manifest = fromKit(`${packageName}/package.json`);
+        const key = `.${specifier.slice(packageName.length)}/${subpath}`;
+        return (typeof manifest.exports === 'object' &&
+            manifest.exports !== null &&
+            key in manifest.exports);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where the shell's page module is: the one `preview.shell.page` names, a
+ * path in the kit or a package resolved from the kit's root, as the shell
+ * itself is; or, with none named, the module at the shell's specifier
+ * followed by `/page`, when the shell is named as a package specifier and
+ * its package has one. A shell with no page has none, and the host page
+ * starts empty.
+ *
+ * @param kitRoot - The kit's root directory.
+ * @param shell - The shell module, as `preview.shell` names it.
+ * @param page - The page module, as `preview.shell.page` names it.
+ * @returns The page module's absolute path, or `undefined` with no page.
+ */
+function resolveShellPage(kitRoot, shell, page) {
+    const fromKit = createRequire(resolve(kitRoot, 'package.json'));
+    if (page === undefined) {
+        if (isModulePath(kitRoot, shell))
+            return undefined;
+        try {
+            return fromKit.resolve(`${shell}/page`);
+        }
+        catch (error) {
+            // A package that exports no page has none; one whose export cannot
+            // be loaded is a mistake worth naming.
+            const code = error.code;
+            if (code === 'ERR_PACKAGE_PATH_NOT_EXPORTED' ||
+                (code === 'MODULE_NOT_FOUND' && !packageExports(fromKit, shell, 'page'))) {
+                return undefined;
+            }
+            return fail(`the shell '${shell}' exports a page at '${shell}/page' that does not resolve: ${error.message}`);
+        }
+    }
+    if (isModulePath(kitRoot, page)) {
+        const inKit = resolve(kitRoot, page);
+        if (!existsSync(inKit)) {
+            fail(`preview.shell.page names a module that does not exist: ${inKit}`);
+        }
+        return inKit;
+    }
+    try {
+        return fromKit.resolve(page);
+    }
+    catch {
+        return fail(`preview.shell.page '${page}' is neither a module in the kit nor a package installed in it (resolved from ${kitRoot}). ` +
+            `Give a path relative to the kit root, or the page module of an installed shell, such as '${CHARCELL_SHELL}/page'.`);
+    }
+}
+/** Whether a module's source imports the shell shipped with the preview. */
+const IMPORTS_CHARCELL_SHELL = new RegExp(`(?:from\\s*|import\\s*\\(\\s*|require\\s*\\(\\s*)['"]${CHARCELL_SHELL.replace(/\./g, '\\.')}['"]`);
+/**
+ * Where the shell shipped with the preview is, when the kit's shell is it:
+ * the shell module itself when `preview.shell` names it, or the module it
+ * resolves to from a module of the kit's that imports it to configure it.
+ * `undefined` under a shell of the kit's own, or when the kit's module
+ * imports it from a package the kit has not installed.
+ */
+function resolveCharcellShell(shell, shellModuleAbsolute) {
+    if (shell === CHARCELL_SHELL)
+        return shellModuleAbsolute;
+    let source;
+    try {
+        source = readFileSync(shellModuleAbsolute, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    if (!IMPORTS_CHARCELL_SHELL.test(source))
+        return undefined;
+    try {
+        return createRequire(shellModuleAbsolute).resolve(CHARCELL_SHELL);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPackageVersion(kitRoot) {
+    const packagePath = resolve(kitRoot, 'package.json');
+    if (!existsSync(packagePath))
+        return undefined;
+    // A package.json that is not JSON has no version to read; `check` reports it.
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(packagePath, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const version = manifest?.version;
+    return typeof version === 'string' ? version : undefined;
+}
+/**
+ * The kit configuration's `parts`, each root's list of part names; what is
+ * not a list of names is left out, as the kit's build reports it.
+ */
+function partsOf(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    const parts = {};
+    for (const [root, rootParts] of Object.entries(value)) {
+        if (Array.isArray(rootParts))
+            parts[root] = rootParts.filter((part) => typeof part === 'string' && part !== '');
+    }
+    return parts;
+}
+/** scaffold-ui-kit, loaded as the CommonJS package it is. */
+function scaffoldUiKit() {
+    return createRequire(import.meta.url)('scaffold-ui-kit');
+}
+/**
+ * The scaffold-ui-kit the kit has installed, when it has the resolver, so
+ * the preview reads the configuration as the kit's own build does; else the
+ * preview's own copy.
+ */
+function kitResolver(kitRoot) {
+    const own = scaffoldUiKit();
+    let installed;
+    try {
+        installed = createRequire(resolve(kitRoot, 'package.json'))('scaffold-ui-kit');
+    }
+    catch {
+        return own;
+    }
+    return typeof installed.resolveKitConfiguration === 'function'
+        ? installed
+        : own;
+}
+/**
+ * The problems that keep a value from reaching the browser as JSON, each
+ * naming where in the value it sits: a function, `undefined` in a list, a
+ * number JSON has no form for, and an object other than a plain one or a
+ * list (a regular expression, a date, a map).
+ *
+ * @param value - The value.
+ * @param path - Where the value sits, as `preview.options`.
+ * @returns One message per problem.
+ * @example
+ * ```ts
+ * jsonProblems({ apply: () => {} }, 'preview.options[0]');
+ * // ["preview.options[0].apply is a function, which can't be sent to the browser as JSON"]
+ * ```
+ */
+export function jsonProblems(value, path, ancestors = new WeakMap()) {
+    const unsendable = (what) => [
+        `${path} is ${what}, which can't be sent to the browser as JSON`,
+    ];
+    if (value === null)
+        return [];
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return [];
+        case 'number':
+            return Number.isFinite(value) ? [] : unsendable(String(value));
+        case 'undefined':
+            return unsendable('undefined');
+        case 'function':
+            return unsendable('a function');
+        case 'bigint':
+        case 'symbol':
+            return unsendable(`a ${typeof value}`);
+    }
+    const object = value;
+    // An object inside itself has no end to write out.
+    const outer = ancestors.get(object);
+    if (outer !== undefined)
+        return [
+            `${path} is ${outer} again, a cycle that can't be sent to the browser as JSON`,
+        ];
+    const prototype = Object.getPrototypeOf(object);
+    if (!Array.isArray(object) &&
+        prototype !== Object.prototype &&
+        prototype !== null)
+        return unsendable(`${object.constructor?.name ?? 'an object'} object`);
+    ancestors.set(object, path);
+    const problems = Array.isArray(object)
+        ? object.flatMap((entry, index) => jsonProblems(entry, `${path}[${index}]`, ancestors))
+        : Object.entries(object)
+            .filter(([, entry]) => entry !== undefined)
+            .flatMap(([key, entry]) => jsonProblems(entry, `${path}.${key}`, ancestors));
+    // Only an ancestor makes a cycle; the same object twice side by side is fine.
+    ancestors.delete(object);
+    return problems;
+}
+/**
+ * Finds the kit configuration (`--configuration`, the kit's `package.json`
+ * pointer, or `scaffold-ui-kit.ts` or `scaffold-ui-kit.json` at the kit
+ * root) and resolves the preview context from its `preview` block.
+ *
+ * @param kitRoot - The kit root.
+ * @param options - The configuration file a command was given, if any.
+ * @returns The context.
+ */
+export function loadPreviewContext(kitRoot, options = {}) {
+    const resolver = kitResolver(kitRoot);
+    let resolved;
+    try {
+        resolved = resolver.resolveKitConfiguration(kitRoot, options);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+    const configurationPath = resolved.file.path;
+    const configurationName = resolved.file.name;
+    const warnings = [...resolved.warnings];
+    const configurationModules = new Set(resolved.modules ?? []);
+    const kitConfiguration = resolved.configuration;
+    const authoredBlock = kitConfiguration.preview;
+    if (!isPlainObject(authoredBlock)) {
+        fail(`${configurationName} has no preview block${'extensions' in kitConfiguration
+            ? "; the preview's settings go in a top-level 'preview' block, not 'extensions'"
+            : ''}`);
+    }
+    const authored = authoredBlock;
+    // A misspelled key would otherwise go unread without a word: every unknown
+    // key fails, the block's and each object's inside it, all named at once.
+    const unknownKeys = [
+        ...unknownKeyProblems(authored, PREVIEW_KEYS, 'preview', "the 'preview' block", PREVIEW_KEY_REPLACEMENTS),
+        ...(Array.isArray(authored.sources) ? authored.sources : []).flatMap((source, index) => source && typeof source === 'object' && !Array.isArray(source)
+            ? unknownKeyProblems(source, SOURCE_KEYS, `preview.sources[${index}]`, 'a source', SOURCE_KEY_REPLACEMENTS)
+            : []),
+        ...(isPlainObject(authored.codeBlock)
+            ? unknownKeyProblems(authored.codeBlock, CODE_BLOCK_KEYS, 'preview.codeBlock', 'a code block')
+            : []),
+        ...(isPlainObject(authored.setupModules)
+            ? unknownKeyProblems(authored.setupModules, ALL_TARGETS, 'preview.setupModules', "the 'setupModules' map")
+            : []),
+        ...(isPlainObject(authored.landing)
+            ? unknownKeyProblems(authored.landing, LANDING_KEYS, 'preview.landing', 'the landing entry')
+            : []),
+        ...(isPlainObject(authored.handWrittenComponents)
+            ? Object.entries(authored.handWrittenComponents).flatMap(([name, mapping]) => isPlainObject(mapping)
+                ? unknownKeyProblems(mapping, HAND_WRITTEN_KEYS, `preview.handWrittenComponents.${name}`, 'a hand-written component')
+                : [])
+            : []),
+    ];
+    if (unknownKeys.length > 0)
+        fail(unknownKeys.join('\n[preview] '));
+    if (!Array.isArray(authored.sources) || authored.sources.length === 0) {
+        fail('preview.sources must be a non-empty array');
+    }
+    authored.sources.forEach(validateSource);
+    const shellSetting = authored.shell;
+    if (shellSetting === undefined || shellSetting === '') {
+        fail(`preview.shell is required: the shell that renders the preview's interface, as a package specifier or a module path relative to the kit root. ` +
+            `To use the shell shipped with the preview, install charcell and @zag-js/react and set shell: '${CHARCELL_SHELL}'.`);
+    }
+    const shellProblem = shellSettingProblem(shellSetting);
+    if (shellProblem !== undefined)
+        fail(shellProblem);
+    const shell = typeof shellSetting === 'string'
+        ? shellSetting
+        : shellSetting.module;
+    const shellPage = typeof shellSetting === 'string'
+        ? undefined
+        : shellSetting.page;
+    const canvas = authored.canvas;
+    if (canvas !== undefined &&
+        (!isPlainObject(canvas) ||
+            typeof canvas.namePrefix !== 'string' ||
+            canvas.namePrefix === '')) {
+        fail("preview.canvas must be { namePrefix, pageBackground?, extraCss? }: namePrefix the prefix for the names the preview sets in each frame, such as 'my-ui-kit'");
+    }
+    for (const key of ['options', 'themes']) {
+        if (authored[key] !== undefined && !Array.isArray(authored[key]))
+            fail(`preview.${key} must be a list`);
+    }
+    for (const key of [
+        'mount',
+        'viewCanvas',
+        'controlHints',
+        'labels',
+    ]) {
+        if (authored[key] !== undefined && !isPlainObject(authored[key]))
+            fail(`preview.${key} must be an object`);
+    }
+    // What the preview's pages read reaches them as JSON, so it must be JSON.
+    const unsendable = PREVIEW_BROWSER_KEYS.filter((key) => authored[key] !== undefined).flatMap((key) => jsonProblems(authored[key], `preview.${key}`));
+    if (unsendable.length > 0)
+        fail(unsendable.join('\n[preview] '));
+    const colorTokens = authored.controlHints?.colorTokens;
+    if (colorTokens !== undefined && !Array.isArray(colorTokens))
+        fail('preview.controlHints.colorTokens must be a list of tokens');
+    const configuration = {
+        ...authored,
+        options: authored.options ?? [],
+        themes: authored.themes ?? [],
+        // The kit's name, made safe for the names it prefixes, by default.
+        canvas: authored.canvas ?? {
+            namePrefix: (kitConfiguration.name ?? 'kit')
+                .replace(/[^A-Za-z0-9_-]/g, '-')
+                .replace(/^-+|-+$/g, ''),
+        },
+        shell,
+        ...(authored.controlHints
+            ? {
+                controlHints: {
+                    ...authored.controlHints,
+                    ...(colorTokens
+                        ? { colorTokens: colorTokens.map((token) => token ?? null) }
+                        : {}),
+                },
+            }
+            : {}),
+    };
+    let omitPattern;
+    if (configuration.omitPattern !== undefined) {
+        try {
+            omitPattern = new RegExp(configuration.omitPattern);
+        }
+        catch {
+            fail(`preview.omitPattern must be a regular expression: ${String(configuration.omitPattern)}`);
+        }
+    }
+    const handWritten = configuration.handWrittenComponents;
+    if (handWritten !== undefined &&
+        (typeof handWritten !== 'object' ||
+            handWritten === null ||
+            Array.isArray(handWritten) ||
+            Object.values(handWritten).some((value) => typeof value !== 'string' &&
+                (typeof value !== 'object' ||
+                    value === null ||
+                    typeof value.template !== 'string' ||
+                    (value.slots !== undefined &&
+                        (typeof value.slots !== 'object' ||
+                            Object.values(value.slots).some((slot) => typeof slot !== 'string'))))))) {
+        fail("preview.handWrittenComponents must map each component name to 'content', a template name, or { template, slots }");
+    }
+    const dedupe = configuration.dedupe;
+    if (dedupe !== undefined &&
+        (!Array.isArray(dedupe) ||
+            dedupe.some((name) => typeof name !== 'string' || name === ''))) {
+        fail('preview.dedupe must be a list of package names');
+    }
+    const htmlStylesheets = configuration.htmlStylesheets;
+    if (htmlStylesheets !== undefined &&
+        (!Array.isArray(htmlStylesheets) ||
+            htmlStylesheets.some((path) => typeof path !== 'string' || path === ''))) {
+        fail('preview.htmlStylesheets must be a list of stylesheet paths, relative to the kit root');
+    }
+    const codeBlock = configuration.codeBlock;
+    if (codeBlock !== undefined &&
+        (typeof codeBlock !== 'object' ||
+            codeBlock === null ||
+            typeof codeBlock.module !== 'string' ||
+            codeBlock.module === '' ||
+            (codeBlock.framework !== undefined &&
+                !['react', 'vue', 'svelte', 'dom'].includes(codeBlock.framework)))) {
+        fail("preview.codeBlock must be { module, framework? }: a module path relative to the kit root, and 'react', 'vue', 'svelte' or 'dom'");
+    }
+    const persistence = configuration.persistence;
+    if (persistence !== undefined &&
+        persistence !== 'url' &&
+        persistence !== 'url-and-local-storage') {
+        fail(`preview.persistence must be 'url' or 'url-and-local-storage', not ${JSON.stringify(persistence)}`);
+    }
+    if (configuration.landing !== undefined) {
+        const problem = landingShapeProblem(configuration.landing);
+        if (problem)
+            fail(problem);
+    }
+    const sources = [...configuration.sources]
+        .sort((a, b) => a.order - b.order)
+        .map((source) => {
+        const templatesDirectoryAbsolute = source.templatesDirectory
+            ? resolve(kitRoot, source.templatesDirectory)
+            : undefined;
+        const storiesDirectoryAbsolute = source.storiesDirectory
+            ? resolve(kitRoot, source.storiesDirectory)
+            : undefined;
+        return {
+            ...source,
+            templatesDirectoryAbsolute,
+            manualModuleAbsolute: source.manualModule
+                ? resolve(kitRoot, source.manualModule)
+                : undefined,
+            storiesDirectoryAbsolute,
+        };
+    });
+    const kitTargets = kitConfiguration.targets;
+    if (kitTargets !== undefined &&
+        (!Array.isArray(kitTargets) ||
+            kitTargets.some((target) => typeof target !== 'string'))) {
+        fail(`${configurationName} targets must be a list of target names`);
+    }
+    const targets = kitTargets
+        ? ALL_TARGETS.filter((target) => kitTargets.includes(target))
+        : [...ALL_TARGETS];
+    const jiti = createJiti(import.meta.url);
+    const importModule = (absolutePath) => jiti.import(absolutePath);
+    const shellModuleAbsolute = resolveShellModule(kitRoot, shell);
+    const shellPageAbsolute = resolveShellPage(kitRoot, shell, shellPage);
+    const charcellShellAbsolute = resolveCharcellShell(shell, shellModuleAbsolute);
+    if (charcellShellAbsolute !== undefined && shellPageAbsolute === undefined) {
+        warnings.push(`preview.shell names a module that configures the charcell shell and no page, so the host page starts empty and light until the shell loads; ` +
+            `name the shell's page beside it: shell: { module: '${shell}', page: '${CHARCELL_SHELL}/page' }`);
+    }
+    const kitPackages = kitPackagesOf(kitRoot, kitConfiguration.packages);
+    const sharedSpecifiers = sharedSpecifiersOf(kitRoot, kitConfiguration.add?.shared, (kitPackages ?? []).map(({ directoryAbsolute }) => directoryAbsolute));
+    return {
+        kitRoot,
+        ...(kitPackages === undefined ? {} : { kitPackages }),
+        configurationPath,
+        configurationModules: [...configurationModules].filter((module) => module !== configurationPath),
+        warnings,
+        kitName: kitConfiguration.name ?? 'kit',
+        kitVersion: readPackageVersion(kitRoot),
+        targets,
+        buildsHtml: kitTargets?.includes('html') ?? false,
+        svelteMode: kitConfiguration.svelte?.mode === 'runes' ? 'runes' : 'legacy',
+        generatedRoot: resolve(kitRoot, '.preview-generated'),
+        staticRoot: resolve(kitRoot, '.preview-static'),
+        configuration,
+        sources,
+        viewsModuleAbsolute: configuration.viewsModule
+            ? resolve(kitRoot, configuration.viewsModule)
+            : undefined,
+        codeBlockModuleAbsolute: configuration.codeBlock
+            ? resolve(kitRoot, configuration.codeBlock.module)
+            : undefined,
+        shellModuleAbsolute: shellModuleAbsolute,
+        ...(shellPageAbsolute === undefined ? {} : { shellPageAbsolute }),
+        ...(charcellShellAbsolute === undefined ? {} : { charcellShellAbsolute }),
+        omitPattern,
+        importModule,
+        styling: {
+            extensions: kitConfiguration.styling ?? [],
+            placement: kitConfiguration.stylesheetPlacement ?? 'in-file',
+            ...(kitConfiguration.bem === undefined
+                ? {}
+                : { bem: kitConfiguration.bem }),
+            ...(kitConfiguration.tailwind === undefined
+                ? {}
+                : { tailwind: kitConfiguration.tailwind }),
+        },
+        parts: partsOf(kitConfiguration.parts),
+        sassLoadPathsAbsolute: (Array.isArray(kitConfiguration.loadPaths)
+            ? kitConfiguration.loadPaths
+            : [])
+            .filter((path) => typeof path === 'string')
+            .map((path) => resolve(kitRoot, path)),
+        sharedModulesAbsolute: sharedSpecifiers
+            .filter(({ source }) => /(^|\/)[^./]*$|\.[cm]?[jt]sx?$/.test(source))
+            .map(({ source }) => resolve(kitRoot, source)),
+        sharedSpecifiers,
+        helperModulesAbsolute: helperModulesOf([
+            kitRoot,
+            ...(kitPackages ?? []).map(({ directoryAbsolute }) => directoryAbsolute),
+        ]),
+    };
+}
+/** The package whose framework-free entries a story's html has in scope. */
+const HELPERS_PACKAGE = '@scaffold-ui-kit/helpers';
+/** The entries of `@scaffold-ui-kit/helpers` that import no framework. */
+const FRAMEWORK_FREE_HELPER_ENTRIES = ['./runtime', './zag'];
+/**
+ * Each framework-free helper entry as the first of the directories that has
+ * the package installed gives it: the package found in `node_modules` from
+ * that directory up, and the entry's file from its `exports` (`import`, else
+ * `default`). Nothing else is searched, so a kit without the package gets
+ * none. An entry the package does not export is left out.
+ */
+function helperModulesOf(directories) {
+    for (const directory of directories) {
+        const packageDirectory = installedPackageDirectory(directory, HELPERS_PACKAGE);
+        if (packageDirectory === undefined)
+            continue;
+        let exportsField;
+        try {
+            exportsField = JSON.parse(readFileSync(resolve(packageDirectory, 'package.json'), 'utf8')).exports;
+        }
+        catch {
+            continue;
+        }
+        if (!isPlainObject(exportsField))
+            continue;
+        return FRAMEWORK_FREE_HELPER_ENTRIES.flatMap((entry) => {
+            const target = exportsField[entry];
+            const file = typeof target === 'string'
+                ? target
+                : isPlainObject(target)
+                    ? (target.import ?? target.default)
+                    : undefined;
+            return typeof file === 'string'
+                ? [realpathSync(resolve(packageDirectory, file))]
+                : [];
+        });
+    }
+    return [];
+}
+/**
+ * The directory of a package installed for `start`, as Node finds it: in
+ * `node_modules` of `start` or of a directory above it, its links resolved.
+ */
+function installedPackageDirectory(start, name) {
+    let directory = resolve(start);
+    for (;;) {
+        const candidate = resolve(directory, 'node_modules', name);
+        if (existsSync(resolve(candidate, 'package.json'))) {
+            return realpathSync(candidate);
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+}
+/**
+ * The kit's shared modules with the specifier its built files import each
+ * by: the one the kit's `package.json` exports give the module, else the
+ * `specifier` a configuration still names.
+ */
+function sharedSpecifiersOf(kitRoot, sharedModules, packageDirectories) {
+    const authored = (Array.isArray(sharedModules) ? sharedModules : []).filter((sharedModule) => isPlainObject(sharedModule) && typeof sharedModule.source === 'string');
+    const { sharedModulesOf } = scaffoldUiKit();
+    const published = sharedModulesOf(kitRoot, authored.map(({ source }) => ({ source })), packageDirectories);
+    return authored.flatMap((sharedModule, index) => {
+        const specifier = published[index].import ??
+            (typeof sharedModule.specifier === 'string'
+                ? sharedModule.specifier
+                : undefined);
+        return specifier === undefined
+            ? []
+            : [{ source: sharedModule.source, specifier }];
+    });
+}
+/**
+ * The kit's packages besides the kit root's, from its configuration's
+ * `packages`: the styles package, then each target's, their
+ * directories resolved against the kit root. `undefined` for a kit without
+ * `packages`; an entry without a name and directory is left out, as the
+ * kit's build reports it.
+ */
+function kitPackagesOf(kitRoot, packages) {
+    if (!isPlainObject(packages))
+        return undefined;
+    const roles = ['styles', ...ALL_TARGETS];
+    return roles.flatMap((role) => {
+        const entry = packages[role];
+        if (!isPlainObject(entry) ||
+            typeof entry.name !== 'string' ||
+            entry.name === '' ||
+            typeof entry.directory !== 'string' ||
+            entry.directory === '')
+            return [];
+        return [
+            {
+                role,
+                name: entry.name,
+                directoryAbsolute: resolve(kitRoot, entry.directory),
+            },
+        ];
+    });
+}