@pwfabric/cli 0.0.0-stage → 1.0.0-rc.1

package/dist/dev/theme.js

@@ -0,0 +1,185 @@
+/**
+ * The app's appearance: resolving a theme named by `use` against the themes
+ * the app and its packs carry, and the stylesheet the shell links so the page
+ * has its identity before any script runs.
+ */
+import { DEFAULT_APPEARANCE_THEME, findAllowedWebfont, mergeSurfaceThemes, parseFontStack, resolveAppearanceMode, resolveDarkTheme, surfaceThemeToCSS, } from '@pwfabric/contracts';
+import { isRecord } from './sources.js';
+/** Builds a {@link ThemeAtom} from a `ui-appearance` manifest, or null when it carries no token set. */
+export function themeAtomOf(id, manifest, from) {
+    if (!isRecord(manifest) || !isRecord(manifest['theme']))
+        return null;
+    const manifestId = typeof manifest['id'] === 'string' ? manifest['id'] : undefined;
+    return {
+        id,
+        ...(manifestId && manifestId !== id ? { manifestId } : {}),
+        theme: manifest['theme'],
+        ...(isRecord(manifest['darkTheme']) ? { darkTheme: manifest['darkTheme'] } : {}),
+        from,
+    };
+}
+/**
+ * The theme a name points at. Matched as given, then as `theme-<name>`, then
+ * with an `appearance-` / `theme-` prefix removed; the first atom wins (the
+ * app's own themes come before its packs').
+ */
+export function findTheme(name, themes) {
+    const bare = name.trim().replace(/^(appearance|theme)-/, '');
+    const wanted = [name.trim(), `theme-${bare}`, bare];
+    for (const w of wanted) {
+        const hit = themes.find((t) => t.id === w || t.manifestId === w);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/** Per-group merge, `over` winning. */
+export function mergeGroups(base, over) {
+    const out = {};
+    for (const [k, v] of Object.entries(base))
+        out[k] = isRecord(v) ? { ...v } : v;
+    if (isRecord(over)) {
+        for (const [k, v] of Object.entries(over)) {
+            const prev = out[k];
+            out[k] = isRecord(v) && isRecord(prev) ? { ...prev, ...v } : v;
+        }
+    }
+    return out;
+}
+function resolveConfig(doc, themes, diagnostics, path) {
+    const use = doc['use'];
+    if (typeof use !== 'string' || !use.trim())
+        return doc;
+    const theme = findTheme(use, themes);
+    if (!theme) {
+        diagnostics.push({
+            severity: 'warning',
+            code: 'THEME_NOT_FOUND',
+            message: `appearance names theme "${use}", which neither the app nor its packs carry (known: ${themes.map((t) => t.id).join(', ') || 'none'}); the runner falls back to its built-in presets`,
+            path,
+        });
+        return doc;
+    }
+    const { use: _use, ...rest } = doc;
+    const out = { ...rest, theme: mergeGroups(theme.theme, rest['theme']) };
+    if (theme.darkTheme)
+        out['darkTheme'] = mergeGroups(theme.darkTheme, rest['darkTheme']);
+    return out;
+}
+/**
+ * The app-wide appearance as the envelope carries it. A theme named by `use`
+ * is resolved to its tokens here, so the published app does not depend on
+ * the runner knowing the name. The three shapes a reader accepts are kept:
+ * a reference (`{ config }`) stays a reference, everything else becomes a
+ * bare configuration.
+ */
+export function resolveAppearance(doc, themes, diagnostics, path = 'app/definitions/appearance.json') {
+    if (!isRecord(doc))
+        return undefined;
+    if (isRecord(doc['config']))
+        return { ...doc, config: resolveConfig(doc['config'], themes, diagnostics, path) };
+    return resolveConfig(doc, themes, diagnostics, path);
+}
+/** The configuration inside any of the three appearance shapes. */
+export function appearanceConfigOf(doc) {
+    if (!doc)
+        return undefined;
+    return isRecord(doc['config']) ? doc['config'] : doc;
+}
+function declList(vars) {
+    return Object.entries(vars)
+        .map(([name, value]) => `  ${name}: ${value};`)
+        .join('\n');
+}
+function modeBlocks(policy, light, dark, darkOverLight) {
+    if (policy === 'light')
+        return `:root, [data-pw-surface] {\n${light}\n}`;
+    if (policy === 'dark')
+        return `:root, [data-pw-surface] {\n${darkOverLight}\n}`;
+    return `:root, [data-pw-surface] {
+${light}
+}
+
+:root[data-pw-theme="dark"],
+[data-pw-surface][data-pw-theme="dark"] {
+${dark}
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-pw-theme="light"]),
+  [data-pw-surface]:not([data-pw-theme="light"]) {
+${dark}
+  }
+}`;
+}
+/**
+ * `assets/theme.css`: the full token set as custom properties (light, the
+ * dark variant per the mode policy) and the document binding — page margin,
+ * body font and colours — so the app wears its identity before hydration.
+ */
+export function buildThemeCss(config) {
+    const cfg = config;
+    const { policy, contrast } = resolveAppearanceMode(cfg);
+    const options = { contrast };
+    const lightVars = surfaceThemeToCSS(cfg?.theme, DEFAULT_APPEARANCE_THEME, undefined, options);
+    if (isRecord(cfg?.styleVariables)) {
+        for (const [key, value] of Object.entries(cfg.styleVariables)) {
+            if (typeof value !== 'string')
+                continue;
+            lightVars[key.startsWith('--') ? key : `--${key}`] = value;
+        }
+    }
+    const light = mergeSurfaceThemes(DEFAULT_APPEARANCE_THEME, cfg?.theme);
+    const darkVars = surfaceThemeToCSS(resolveDarkTheme(light, cfg?.darkTheme), undefined, undefined, options);
+    return `${modeBlocks(policy, declList(lightVars), declList(darkVars), declList({ ...lightVars, ...darkVars }))}
+
+html, body {
+  margin: 0;
+  font-family: var(--pw-font-family, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif);
+  font-size: var(--pw-font-size-base, 16px);
+  color: var(--pw-color-text, #1e293b);
+  background: var(--pw-color-background, #ffffff);
+}
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--pw-font-family-heading, inherit);
+}
+code, pre, kbd {
+  font-family: var(--pw-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+}
+`;
+}
+/**
+ * The webfonts a theme names and may load: the first family of the body,
+ * heading and mono stacks, and only when it is on the engine's allow-list. A
+ * free-text family never becomes a URL.
+ */
+export function themeWebfonts(config) {
+    const theme = config?.['theme'];
+    const typography = isRecord(theme) && isRecord(theme['typography']) ? theme['typography'] : undefined;
+    const out = [];
+    for (const key of ['fontFamily', 'headingFontFamily', 'monoFontFamily']) {
+        const stack = typography?.[key];
+        const first = parseFontStack(typeof stack === 'string' ? stack : undefined)[0];
+        const font = first === undefined ? undefined : findAllowedWebfont(first);
+        if (font && !out.some((f) => f.family === font.family))
+            out.push(font);
+    }
+    return out;
+}
+/** One stylesheet address for the families, or null when there are none. */
+export function webfontStylesheetHref(fonts) {
+    if (fonts.length === 0)
+        return null;
+    const families = fonts.map((f) => {
+        const weights = [...new Set(f.weights)].sort((a, b) => a - b);
+        const name = encodeURIComponent(f.family).replace(/%20/g, '+');
+        if (weights.length === 0)
+            return `family=${name}`;
+        if (!f.italic)
+            return `family=${name}:wght@${weights.join(';')}`;
+        const tuples = [...weights.map((w) => `0,${w}`), ...weights.map((w) => `1,${w}`)];
+        return `family=${name}:ital,wght@${tuples.join(';')}`;
+    });
+    return `https://fonts.googleapis.com/css2?${families.join('&')}&display=swap`;
+}
+//# sourceMappingURL=theme.js.map

package/dist/dev/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../../src/dev/theme.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,GAGlB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAavC,wGAAwG;AACxG,MAAM,UAAU,WAAW,CAAC,EAAU,EAAE,QAAiB,EAAE,IAAY;IACrE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IACpE,MAAM,UAAU,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAClF,OAAO;QACL,EAAE;QACF,GAAG,CAAC,UAAU,IAAI,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC;QACxB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,IAAI;KACL,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,MAA4B;IAClE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAA;IAC5D,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,IAAI,EAAE,EAAE,IAAI,CAAC,CAAA;IACnD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,CAAA;QAChE,IAAI,GAAG;YAAE,OAAO,GAAG,CAAA;IACrB,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,WAAW,CAAC,IAA6B,EAAE,IAAa;IACtE,MAAM,GAAG,GAA4B,EAAE,CAAA;IACvC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9E,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAA;YACnB,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;QAChE,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,aAAa,CACpB,GAA4B,EAC5B,MAA4B,EAC5B,WAAiC,EACjC,IAAY;IAEZ,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAA;IACtB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;QAAE,OAAO,GAAG,CAAA;IACtD,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IACpC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,WAAW,CAAC,IAAI,CAAC;YACf,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,2BAA2B,GAAG,wDACrC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MACxC,kDAAkD;YAClD,IAAI;SACL,CAAC,CAAA;QACF,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,CAAA;IAClC,MAAM,GAAG,GAA4B,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAA;IAChG,IAAI,KAAK,CAAC,SAAS;QAAE,GAAG,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAA;IACvF,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAY,EACZ,MAA4B,EAC5B,WAAiC,EACjC,IAAI,GAAG,iCAAiC;IAExC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IACpC,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,CAAA;IAC/G,OAAO,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,CAAA;AACtD,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,kBAAkB,CAAC,GAAwC;IACzE,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAA;IAC1B,OAAO,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;AACtD,CAAC;AAED,SAAS,QAAQ,CAAC,IAA4B;IAC5C,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;SACxB,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,KAAK,KAAK,GAAG,CAAC;SAC9C,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC;AAED,SAAS,UAAU,CAAC,MAAmC,EAAE,KAAa,EAAE,IAAY,EAAE,aAAqB;IACzG,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,+BAA+B,KAAK,KAAK,CAAA;IACxE,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,+BAA+B,aAAa,KAAK,CAAA;IAC/E,OAAO;EACP,KAAK;;;;;EAKL,IAAI;;;;;;EAMJ,IAAI;;EAEJ,CAAA;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAA2C;IACvE,MAAM,GAAG,GAAG,MAAkH,CAAA;IAC9H,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAA;IACvD,MAAM,OAAO,GAAG,EAAE,QAAQ,EAAE,CAAA;IAC5B,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,wBAAwB,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;IAC7F,IAAI,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,CAAC;QAClC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;YAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,SAAQ;YACvC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,KAAK,CAAA;QAC5D,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,kBAAkB,CAAC,wBAAwB,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;IACtE,MAAM,QAAQ,GAAG,iBAAiB,CAAC,gBAAgB,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;IAC1G,OAAO,GAAG,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,EAAE,GAAG,SAAS,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;;;;;;;;;;;;;;;CAe/G,CAAA;AACD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAA2C;IACvE,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,CAAA;IAC/B,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACrG,MAAM,GAAG,GAAqB,EAAE,CAAA;IAChC,KAAK,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,CAAC,EAAE,CAAC;QACxE,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC,GAAG,CAAC,CAAA;QAC/B,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9E,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAA;QACxE,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACxE,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,qBAAqB,CAAC,KAAgC;IACpE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACnC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC/B,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QAC7D,MAAM,IAAI,GAAG,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;QAC9D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,UAAU,IAAI,EAAE,CAAA;QACjD,IAAI,CAAC,CAAC,CAAC,MAAM;YAAE,OAAO,UAAU,IAAI,SAAS,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;QAChE,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;QACjF,OAAO,UAAU,IAAI,cAAc,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;IACvD,CAAC,CAAC,CAAA;IACF,OAAO,qCAAqC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,CAAA;AAC/E,CAAC","sourcesContent":["/**\n * The app's appearance: resolving a theme named by `use` against the themes\n * the app and its packs carry, and the stylesheet the shell links so the page\n * has its identity before any script runs.\n */\nimport {\n  DEFAULT_APPEARANCE_THEME,\n  findAllowedWebfont,\n  mergeSurfaceThemes,\n  parseFontStack,\n  resolveAppearanceMode,\n  resolveDarkTheme,\n  surfaceThemeToCSS,\n  type AllowedWebfont,\n  type SurfaceTheme,\n} from '@pwfabric/contracts'\nimport type { AssembleDiagnostic } from './diagnostics.js'\nimport { isRecord } from './sources.js'\n\n/** A `ui-appearance` atom an app can name: its id and its token sets. */\nexport interface ThemeAtom {\n  readonly id: string\n  /** The manifest's own `id`, when it differs from the path-derived one. */\n  readonly manifestId?: string\n  readonly theme: Record<string, unknown>\n  readonly darkTheme?: Record<string, unknown>\n  /** Where it came from, for diagnostics. */\n  readonly from: string\n}\n\n/** Builds a {@link ThemeAtom} from a `ui-appearance` manifest, or null when it carries no token set. */\nexport function themeAtomOf(id: string, manifest: unknown, from: string): ThemeAtom | null {\n  if (!isRecord(manifest) || !isRecord(manifest['theme'])) return null\n  const manifestId = typeof manifest['id'] === 'string' ? manifest['id'] : undefined\n  return {\n    id,\n    ...(manifestId && manifestId !== id ? { manifestId } : {}),\n    theme: manifest['theme'],\n    ...(isRecord(manifest['darkTheme']) ? { darkTheme: manifest['darkTheme'] } : {}),\n    from,\n  }\n}\n\n/**\n * The theme a name points at. Matched as given, then as `theme-<name>`, then\n * with an `appearance-` / `theme-` prefix removed; the first atom wins (the\n * app's own themes come before its packs').\n */\nexport function findTheme(name: string, themes: readonly ThemeAtom[]): ThemeAtom | undefined {\n  const bare = name.trim().replace(/^(appearance|theme)-/, '')\n  const wanted = [name.trim(), `theme-${bare}`, bare]\n  for (const w of wanted) {\n    const hit = themes.find((t) => t.id === w || t.manifestId === w)\n    if (hit) return hit\n  }\n  return undefined\n}\n\n/** Per-group merge, `over` winning. */\nexport function mergeGroups(base: Record<string, unknown>, over: unknown): Record<string, unknown> {\n  const out: Record<string, unknown> = {}\n  for (const [k, v] of Object.entries(base)) out[k] = isRecord(v) ? { ...v } : v\n  if (isRecord(over)) {\n    for (const [k, v] of Object.entries(over)) {\n      const prev = out[k]\n      out[k] = isRecord(v) && isRecord(prev) ? { ...prev, ...v } : v\n    }\n  }\n  return out\n}\n\nfunction resolveConfig(\n  doc: Record<string, unknown>,\n  themes: readonly ThemeAtom[],\n  diagnostics: AssembleDiagnostic[],\n  path: string\n): Record<string, unknown> {\n  const use = doc['use']\n  if (typeof use !== 'string' || !use.trim()) return doc\n  const theme = findTheme(use, themes)\n  if (!theme) {\n    diagnostics.push({\n      severity: 'warning',\n      code: 'THEME_NOT_FOUND',\n      message: `appearance names theme \"${use}\", which neither the app nor its packs carry (known: ${\n        themes.map((t) => t.id).join(', ') || 'none'\n      }); the runner falls back to its built-in presets`,\n      path,\n    })\n    return doc\n  }\n  const { use: _use, ...rest } = doc\n  const out: Record<string, unknown> = { ...rest, theme: mergeGroups(theme.theme, rest['theme']) }\n  if (theme.darkTheme) out['darkTheme'] = mergeGroups(theme.darkTheme, rest['darkTheme'])\n  return out\n}\n\n/**\n * The app-wide appearance as the envelope carries it. A theme named by `use`\n * is resolved to its tokens here, so the published app does not depend on\n * the runner knowing the name. The three shapes a reader accepts are kept:\n * a reference (`{ config }`) stays a reference, everything else becomes a\n * bare configuration.\n */\nexport function resolveAppearance(\n  doc: unknown,\n  themes: readonly ThemeAtom[],\n  diagnostics: AssembleDiagnostic[],\n  path = 'app/definitions/appearance.json'\n): Record<string, unknown> | undefined {\n  if (!isRecord(doc)) return undefined\n  if (isRecord(doc['config'])) return { ...doc, config: resolveConfig(doc['config'], themes, diagnostics, path) }\n  return resolveConfig(doc, themes, diagnostics, path)\n}\n\n/** The configuration inside any of the three appearance shapes. */\nexport function appearanceConfigOf(doc: Record<string, unknown> | undefined): Record<string, unknown> | undefined {\n  if (!doc) return undefined\n  return isRecord(doc['config']) ? doc['config'] : doc\n}\n\nfunction declList(vars: Record<string, string>): string {\n  return Object.entries(vars)\n    .map(([name, value]) => `  ${name}: ${value};`)\n    .join('\\n')\n}\n\nfunction modeBlocks(policy: 'light' | 'dark' | 'system', light: string, dark: string, darkOverLight: string): string {\n  if (policy === 'light') return `:root, [data-pw-surface] {\\n${light}\\n}`\n  if (policy === 'dark') return `:root, [data-pw-surface] {\\n${darkOverLight}\\n}`\n  return `:root, [data-pw-surface] {\n${light}\n}\n\n:root[data-pw-theme=\"dark\"],\n[data-pw-surface][data-pw-theme=\"dark\"] {\n${dark}\n}\n\n@media (prefers-color-scheme: dark) {\n  :root:not([data-pw-theme=\"light\"]),\n  [data-pw-surface]:not([data-pw-theme=\"light\"]) {\n${dark}\n  }\n}`\n}\n\n/**\n * `assets/theme.css`: the full token set as custom properties (light, the\n * dark variant per the mode policy) and the document binding — page margin,\n * body font and colours — so the app wears its identity before hydration.\n */\nexport function buildThemeCss(config: Record<string, unknown> | undefined): string {\n  const cfg = config as { theme?: SurfaceTheme; darkTheme?: SurfaceTheme; styleVariables?: Record<string, unknown> } | undefined\n  const { policy, contrast } = resolveAppearanceMode(cfg)\n  const options = { contrast }\n  const lightVars = surfaceThemeToCSS(cfg?.theme, DEFAULT_APPEARANCE_THEME, undefined, options)\n  if (isRecord(cfg?.styleVariables)) {\n    for (const [key, value] of Object.entries(cfg.styleVariables)) {\n      if (typeof value !== 'string') continue\n      lightVars[key.startsWith('--') ? key : `--${key}`] = value\n    }\n  }\n  const light = mergeSurfaceThemes(DEFAULT_APPEARANCE_THEME, cfg?.theme)\n  const darkVars = surfaceThemeToCSS(resolveDarkTheme(light, cfg?.darkTheme), undefined, undefined, options)\n  return `${modeBlocks(policy, declList(lightVars), declList(darkVars), declList({ ...lightVars, ...darkVars }))}\n\nhtml, body {\n  margin: 0;\n  font-family: var(--pw-font-family, ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif);\n  font-size: var(--pw-font-size-base, 16px);\n  color: var(--pw-color-text, #1e293b);\n  background: var(--pw-color-background, #ffffff);\n}\nh1, h2, h3, h4, h5, h6 {\n  font-family: var(--pw-font-family-heading, inherit);\n}\ncode, pre, kbd {\n  font-family: var(--pw-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace);\n}\n`\n}\n\n/**\n * The webfonts a theme names and may load: the first family of the body,\n * heading and mono stacks, and only when it is on the engine's allow-list. A\n * free-text family never becomes a URL.\n */\nexport function themeWebfonts(config: Record<string, unknown> | undefined): AllowedWebfont[] {\n  const theme = config?.['theme']\n  const typography = isRecord(theme) && isRecord(theme['typography']) ? theme['typography'] : undefined\n  const out: AllowedWebfont[] = []\n  for (const key of ['fontFamily', 'headingFontFamily', 'monoFontFamily']) {\n    const stack = typography?.[key]\n    const first = parseFontStack(typeof stack === 'string' ? stack : undefined)[0]\n    const font = first === undefined ? undefined : findAllowedWebfont(first)\n    if (font && !out.some((f) => f.family === font.family)) out.push(font)\n  }\n  return out\n}\n\n/** One stylesheet address for the families, or null when there are none. */\nexport function webfontStylesheetHref(fonts: readonly AllowedWebfont[]): string | null {\n  if (fonts.length === 0) return null\n  const families = fonts.map((f) => {\n    const weights = [...new Set(f.weights)].sort((a, b) => a - b)\n    const name = encodeURIComponent(f.family).replace(/%20/g, '+')\n    if (weights.length === 0) return `family=${name}`\n    if (!f.italic) return `family=${name}:wght@${weights.join(';')}`\n    const tuples = [...weights.map((w) => `0,${w}`), ...weights.map((w) => `1,${w}`)]\n    return `family=${name}:ital,wght@${tuples.join(';')}`\n  })\n  return `https://fonts.googleapis.com/css2?${families.join('&')}&display=swap`\n}\n"]}

package/dist/dev/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The contract between `pwf dev` (./server.ts, written by the dev lane) and
+ * the rest of the CLI.
+ *
+ * `pwf dev` watches a pwpack folder, compiles its atoms with the engine's
+ * compiler, builds an envelope from the folder, and serves a page that boots
+ * the runner against it. When the app declares data or sign-in, it mounts a
+ * local host (../host) that implements the session and data protocols.
+ */
+import type { LocalHost } from '../host/types.js';
+export interface DevServerOptions {
+    /** Absolute path of the pwpack folder to serve. */
+    readonly root: string;
+    /** Port to listen on; 0 picks a free port. Default 4600. */
+    readonly port?: number;
+    /** Host interface to bind. Default 127.0.0.1. */
+    readonly hostname?: string;
+    /** Mount a local host for data and sign-in. Default: only when the app declares them. */
+    readonly localHost?: boolean | LocalHost;
+    /** Called with human-readable progress lines. */
+    readonly log?: (line: string) => void;
+}
+export interface DevServer {
+    /** The URL the app is served at, e.g. http://127.0.0.1:4600/. */
+    readonly url: string;
+    /** Rebuilds now (the watcher also rebuilds on change). */
+    rebuild(): Promise<DevBuildResult>;
+    /** Stops the watcher and the HTTP server. */
+    close(): Promise<void>;
+}
+export interface DevBuildResult {
+    readonly ok: boolean;
+    /** Atoms compiled in this build. */
+    readonly compiled: number;
+    /** Compiler and validation diagnostics, already formatted for a terminal. */
+    readonly diagnostics: readonly string[];
+    readonly ms: number;
+}
+/** Implemented in ./server.ts. */
+export type StartDevServer = (options: DevServerOptions) => Promise<DevServer>;

package/dist/dev/types.js

@@ -0,0 +1,11 @@
+/**
+ * The contract between `pwf dev` (./server.ts, written by the dev lane) and
+ * the rest of the CLI.
+ *
+ * `pwf dev` watches a pwpack folder, compiles its atoms with the engine's
+ * compiler, builds an envelope from the folder, and serves a page that boots
+ * the runner against it. When the app declares data or sign-in, it mounts a
+ * local host (../host) that implements the session and data protocols.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/dev/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/dev/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * The contract between `pwf dev` (./server.ts, written by the dev lane) and\n * the rest of the CLI.\n *\n * `pwf dev` watches a pwpack folder, compiles its atoms with the engine's\n * compiler, builds an envelope from the folder, and serves a page that boots\n * the runner against it. When the app declares data or sign-in, it mounts a\n * local host (../host) that implements the session and data protocols.\n */\n\nimport type { LocalHost } from '../host/types.js'\n\nexport interface DevServerOptions {\n  /** Absolute path of the pwpack folder to serve. */\n  readonly root: string\n  /** Port to listen on; 0 picks a free port. Default 4600. */\n  readonly port?: number\n  /** Host interface to bind. Default 127.0.0.1. */\n  readonly hostname?: string\n  /** Mount a local host for data and sign-in. Default: only when the app declares them. */\n  readonly localHost?: boolean | LocalHost\n  /** Called with human-readable progress lines. */\n  readonly log?: (line: string) => void\n}\n\nexport interface DevServer {\n  /** The URL the app is served at, e.g. http://127.0.0.1:4600/. */\n  readonly url: string\n  /** Rebuilds now (the watcher also rebuilds on change). */\n  rebuild(): Promise<DevBuildResult>\n  /** Stops the watcher and the HTTP server. */\n  close(): Promise<void>\n}\n\nexport interface DevBuildResult {\n  readonly ok: boolean\n  /** Atoms compiled in this build. */\n  readonly compiled: number\n  /** Compiler and validation diagnostics, already formatted for a terminal. */\n  readonly diagnostics: readonly string[]\n  readonly ms: number\n}\n\n/** Implemented in ./server.ts. */\nexport type StartDevServer = (options: DevServerOptions) => Promise<DevServer>\n"]}

package/dist/dev/watcher.d.ts

@@ -0,0 +1,29 @@
+export type WatchMode = 'auto' | 'native' | 'poll';
+export interface WatchOptions {
+    /** Default `auto`: native recursive watching, polling when it is unavailable. */
+    readonly mode?: WatchMode;
+    /** Quiet period before the callback fires. Default 150 ms. */
+    readonly debounceMs?: number;
+    /** Poll interval in `poll` mode. Default 500 ms. */
+    readonly pollMs?: number;
+}
+export interface Watcher {
+    /** `native` or `poll` — what is actually running. */
+    readonly mode: 'native' | 'poll';
+    close(): void;
+}
+/** Whether a change at `rel` (POSIX, relative to the root) should trigger a rebuild. */
+export declare function isWatchedPath(rel: string): boolean;
+/** A function that runs `fn` once `ms` after the last call. */
+export declare function debounce(fn: () => void, ms: number): {
+    (): void;
+    cancel(): void;
+};
+/** A signature of every watched file (path, size, mtime), for polling. */
+export declare function snapshot(root: string): Promise<string>;
+/**
+ * Watches `root` and calls `onChange` after each debounced burst of relevant
+ * changes, with the POSIX paths that changed — or `null` when the platform
+ * could not say (polling, or an event without a file name).
+ */
+export declare function watchFolder(root: string, onChange: (paths: string[] | null) => void, options?: WatchOptions): Watcher;

package/dist/dev/watcher.js

@@ -0,0 +1,150 @@
+/**
+ * Watching an app folder for changes.
+ *
+ * `fs.watch` with `recursive: true` where the platform supports it (Windows,
+ * macOS, Linux on current Node); a polling walk where it does not. Either way
+ * the caller sees one debounced callback per burst of changes, and changes in
+ * the build's own output (`.pwf/build-cache`, `.pwf/out`), version control
+ * and dependencies are ignored. The pack cache (`.pwf/packs`) is watched:
+ * adding a pack is a change the app should pick up.
+ */
+import { watch as fsWatch } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+const IGNORED_SEGMENTS = new Set(['node_modules', '.git', 'dist']);
+const IGNORED_PREFIXES = ['.pwf/build-cache', '.pwf/out'];
+/** Whether a change at `rel` (POSIX, relative to the root) should trigger a rebuild. */
+export function isWatchedPath(rel) {
+    const p = rel.split(sep).join('/').replace(/^\.\//, '');
+    if (!p)
+        return true;
+    if (IGNORED_PREFIXES.some((x) => p === x || p.startsWith(`${x}/`)))
+        return false;
+    return !p.split('/').some((s) => IGNORED_SEGMENTS.has(s));
+}
+/** A function that runs `fn` once `ms` after the last call. */
+export function debounce(fn, ms) {
+    let timer = null;
+    const run = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            fn();
+        }, ms);
+    };
+    run.cancel = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+    };
+    return run;
+}
+/** A signature of every watched file (path, size, mtime), for polling. */
+export async function snapshot(root) {
+    const parts = [];
+    const walk = async (dir) => {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const e of entries) {
+            const full = join(dir, e.name);
+            const rel = relative(root, full);
+            if (!isWatchedPath(rel))
+                continue;
+            if (e.isDirectory())
+                await walk(full);
+            else if (e.isFile()) {
+                const st = await stat(full).catch(() => null);
+                if (st)
+                    parts.push(`${rel}|${st.size}|${st.mtimeMs}`);
+            }
+        }
+    };
+    await walk(root);
+    return parts.sort().join('\n');
+}
+function startPolling(root, onChange, pollMs) {
+    let last = null;
+    let closed = false;
+    let running = false;
+    const tick = async () => {
+        if (running || closed)
+            return;
+        running = true;
+        try {
+            const now = await snapshot(root);
+            if (last !== null && now !== last && !closed)
+                onChange();
+            last = now;
+        }
+        finally {
+            running = false;
+        }
+    };
+    void tick();
+    const timer = setInterval(() => void tick(), pollMs);
+    return {
+        mode: 'poll',
+        close() {
+            closed = true;
+            clearInterval(timer);
+        },
+    };
+}
+/**
+ * Watches `root` and calls `onChange` after each debounced burst of relevant
+ * changes, with the POSIX paths that changed — or `null` when the platform
+ * could not say (polling, or an event without a file name).
+ */
+export function watchFolder(root, onChange, options = {}) {
+    let changed = new Set();
+    const fire = debounce(() => {
+        const paths = changed ? [...changed].sort() : null;
+        changed = new Set();
+        onChange(paths);
+    }, options.debounceMs ?? 150);
+    const note = (path) => {
+        if (path === null)
+            changed = null;
+        else
+            changed?.add(path.split(sep).join('/'));
+        fire();
+    };
+    const mode = options.mode ?? 'auto';
+    if (mode !== 'poll') {
+        let watcher = null;
+        try {
+            watcher = fsWatch(root, { recursive: true }, (_event, filename) => {
+                if (filename === null)
+                    note(null);
+                else if (isWatchedPath(String(filename)))
+                    note(String(filename));
+            });
+        }
+        catch (e) {
+            if (mode === 'native')
+                throw e;
+        }
+        if (watcher) {
+            const w = watcher;
+            // A watcher that dies (the folder is removed, the platform gives up)
+            // must not take the server down; the next edit simply is not seen.
+            w.on('error', () => undefined);
+            return {
+                mode: 'native',
+                close() {
+                    fire.cancel();
+                    w.close();
+                },
+            };
+        }
+    }
+    const poller = startPolling(root, () => note(null), options.pollMs ?? 500);
+    return {
+        mode: 'poll',
+        close() {
+            fire.cancel();
+            poller.close();
+        },
+    };
+}
+//# sourceMappingURL=watcher.js.map

package/dist/dev/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/dev/watcher.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Watching an app folder for changes.\n *\n * `fs.watch` with `recursive: true` where the platform supports it (Windows,\n * macOS, Linux on current Node); a polling walk where it does not. Either way\n * the caller sees one debounced callback per burst of changes, and changes in\n * the build's own output (`.pwf/build-cache`, `.pwf/out`), version control\n * and dependencies are ignored. The pack cache (`.pwf/packs`) is watched:\n * adding a pack is a change the app should pick up.\n */\nimport { watch as fsWatch, type FSWatcher } from 'node:fs'\nimport { readdir, stat } from 'node:fs/promises'\nimport { join, relative, sep } from 'node:path'\n\nexport type WatchMode = 'auto' | 'native' | 'poll'\n\nexport interface WatchOptions {\n  /** Default `auto`: native recursive watching, polling when it is unavailable. */\n  readonly mode?: WatchMode\n  /** Quiet period before the callback fires. Default 150 ms. */\n  readonly debounceMs?: number\n  /** Poll interval in `poll` mode. Default 500 ms. */\n  readonly pollMs?: number\n}\n\nexport interface Watcher {\n  /** `native` or `poll` — what is actually running. */\n  readonly mode: 'native' | 'poll'\n  close(): void\n}\n\nconst IGNORED_SEGMENTS = new Set(['node_modules', '.git', 'dist'])\nconst IGNORED_PREFIXES = ['.pwf/build-cache', '.pwf/out']\n\n/** Whether a change at `rel` (POSIX, relative to the root) should trigger a rebuild. */\nexport function isWatchedPath(rel: string): boolean {\n  const p = rel.split(sep).join('/').replace(/^\\.\\//, '')\n  if (!p) return true\n  if (IGNORED_PREFIXES.some((x) => p === x || p.startsWith(`${x}/`))) return false\n  return !p.split('/').some((s) => IGNORED_SEGMENTS.has(s))\n}\n\n/** A function that runs `fn` once `ms` after the last call. */\nexport function debounce(fn: () => void, ms: number): { (): void; cancel(): void } {\n  let timer: ReturnType<typeof setTimeout> | null = null\n  const run = (): void => {\n    if (timer) clearTimeout(timer)\n    timer = setTimeout(() => {\n      timer = null\n      fn()\n    }, ms)\n  }\n  run.cancel = (): void => {\n    if (timer) clearTimeout(timer)\n    timer = null\n  }\n  return run\n}\n\n/** A signature of every watched file (path, size, mtime), for polling. */\nexport async function snapshot(root: string): Promise<string> {\n  const parts: string[] = []\n  const walk = async (dir: string): Promise<void> => {\n    const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])\n    for (const e of entries) {\n      const full = join(dir, e.name)\n      const rel = relative(root, full)\n      if (!isWatchedPath(rel)) continue\n      if (e.isDirectory()) await walk(full)\n      else if (e.isFile()) {\n        const st = await stat(full).catch(() => null)\n        if (st) parts.push(`${rel}|${st.size}|${st.mtimeMs}`)\n      }\n    }\n  }\n  await walk(root)\n  return parts.sort().join('\\n')\n}\n\nfunction startPolling(root: string, onChange: () => void, pollMs: number): Watcher {\n  let last: string | null = null\n  let closed = false\n  let running = false\n  const tick = async (): Promise<void> => {\n    if (running || closed) return\n    running = true\n    try {\n      const now = await snapshot(root)\n      if (last !== null && now !== last && !closed) onChange()\n      last = now\n    } finally {\n      running = false\n    }\n  }\n  void tick()\n  const timer = setInterval(() => void tick(), pollMs)\n  return {\n    mode: 'poll',\n    close() {\n      closed = true\n      clearInterval(timer)\n    },\n  }\n}\n\n/**\n * Watches `root` and calls `onChange` after each debounced burst of relevant\n * changes, with the POSIX paths that changed — or `null` when the platform\n * could not say (polling, or an event without a file name).\n */\nexport function watchFolder(root: string, onChange: (paths: string[] | null) => void, options: WatchOptions = {}): Watcher {\n  let changed: Set<string> | null = new Set()\n  const fire = debounce(() => {\n    const paths = changed ? [...changed].sort() : null\n    changed = new Set()\n    onChange(paths)\n  }, options.debounceMs ?? 150)\n  const note = (path: string | null): void => {\n    if (path === null) changed = null\n    else changed?.add(path.split(sep).join('/'))\n    fire()\n  }\n  const mode = options.mode ?? 'auto'\n  if (mode !== 'poll') {\n    let watcher: FSWatcher | null = null\n    try {\n      watcher = fsWatch(root, { recursive: true }, (_event, filename) => {\n        if (filename === null) note(null)\n        else if (isWatchedPath(String(filename))) note(String(filename))\n      })\n    } catch (e) {\n      if (mode === 'native') throw e\n    }\n    if (watcher) {\n      const w = watcher\n      // A watcher that dies (the folder is removed, the platform gives up)\n      // must not take the server down; the next edit simply is not seen.\n      w.on('error', () => undefined)\n      return {\n        mode: 'native',\n        close() {\n          fire.cancel()\n          w.close()\n        },\n      }\n    }\n  }\n  const poller = startPolling(root, () => note(null), options.pollMs ?? 500)\n  return {\n    mode: 'poll',\n    close() {\n      fire.cancel()\n      poller.close()\n    },\n  }\n}\n"]}

package/dist/host/definitions.d.ts

@@ -0,0 +1,61 @@
+/**
+ * What the local host reads from the pwpack folder.
+ *
+ *   app/definitions/auth.json      who may enter (definitions.md, `auth.json`)
+ *   app/definitions/entities.json  the collections the host keeps
+ *   app/surfaces/<key>.receipt.json  the pages it serves
+ *   app/data/<typeId>.jsonl | .json  seed rows (a convention of this host)
+ *
+ * Read on every call, never cached: `pwf dev` edits these files while the
+ * host runs, and a definition change must apply without a restart. An absent
+ * file is "not declared"; an unreadable one is reported as an error rather
+ * than guessed around.
+ */
+export interface AuthDeclaration {
+    readonly required: boolean;
+    readonly topology: 'app' | 'external';
+    readonly methods: readonly string[];
+    readonly issuer?: {
+        readonly issuer: string;
+        readonly clientId: string;
+        readonly scopes: readonly string[];
+        readonly audience?: string;
+    };
+    readonly access: {
+        readonly rules: readonly {
+            readonly subject: string;
+            readonly model: string;
+            readonly rule: string;
+        }[];
+    };
+}
+export interface EntityField {
+    readonly name: string;
+    readonly type: string;
+    readonly required: boolean;
+}
+export interface EntityDeclaration {
+    readonly typeId: string;
+    readonly displayName?: string;
+    readonly fields: readonly EntityField[];
+    /** Carried member (not in the spec yet): `"owner"` makes the collection per-visitor. */
+    readonly scope?: string;
+}
+/** `undefined` when the app declares no `auth.json` (or an empty one). */
+export declare function readAuth(root: string): AuthDeclaration | undefined;
+export declare function readEntities(root: string): EntityDeclaration[];
+/** A page key is a file name, never a path. */
+export declare const PAGE_KEY: RegExp;
+export declare function surfaceKeys(root: string): string[];
+export declare function readReceipt(root: string, key: string): Record<string, unknown> | undefined;
+/**
+ * Seed rows for one collection.
+ *
+ * THE CONVENTION (proposed for the spec): `app/data/<typeId>.json` holding
+ * `{ "data": [ …records ] }` — the same `data` envelope a record list answer
+ * uses. A record may carry its own `id`; `createdAt`/`updatedAt` are filled
+ * when absent. Also accepted, for hand-written seed files only:
+ * `app/data/<typeId>.jsonl`, one JSON object per line (blank lines skipped),
+ * read when no `.json` file exists.
+ */
+export declare function readSeed(root: string, typeId: string): Record<string, unknown>[];