@plumix/core 0.1.0

package/dist/test/rpc.d.ts

@@ -0,0 +1,86 @@
+import type { RouterClient } from "@orpc/server";
+import type { RequestAuthenticator } from "../auth/authenticator.js";
+import type { Mailer } from "../auth/mailer/types.js";
+import type { AppContext } from "../context/app.js";
+import type { User, UserRole } from "../db/schema/users.js";
+import type { HookRegistry } from "../hooks/registry.js";
+import type { ActionArgs, ActionName, FilterInput, FilterName, FilterRest } from "../hooks/types.js";
+import type { PluginRegistry } from "../plugin/manifest.js";
+import type { OAuthProviderSummary } from "../runtime/app.js";
+import type { PlumixEnv } from "../runtime/bindings.js";
+import type { Factories } from "./factories.js";
+import type { ActionSpy, FilterSpy } from "./spies.js";
+import { appRouter } from "../rpc/router.js";
+import { createTestDb } from "./harness.js";
+type TestDb = Awaited<ReturnType<typeof createTestDb>>;
+export interface BaseRpcHarnessOptions {
+    readonly hooks?: HookRegistry;
+    /**
+     * Plugin registry seed. Anything contributed via `ctx.registerBlock` /
+     * `ctx.registerMark` lands in the validator's merged registries —
+     * pass a registry produced by `installPlugins` to exercise plugin
+     * block / mark content end-to-end through `entry.update`.
+     */
+    readonly plugins?: PluginRegistry;
+    readonly request?: Request;
+    /**
+     * Runtime environment bindings (KV, R2, etc.) — exposed on `h.env`.
+     * Empty object by default; override for tests that need specific bindings.
+     */
+    readonly env?: PlumixEnv;
+    /**
+     * Provider keys the harness should report on `ctx.oauthProviders`. Pass
+     * `["github"]` etc. when exercising the auth.oauthProviders procedure;
+     * default `[]` matches a passkey-only deploy.
+     */
+    readonly oauthProviders?: readonly OAuthProviderSummary[];
+    /**
+     * Override the default session-cookie authenticator. Tests for
+     * external-IdP-style flows (cfAccess, custom guards) pass an
+     * instance here; the RPC `authenticated` middleware delegates to it.
+     */
+    readonly authenticator?: RequestAuthenticator;
+    /**
+     * Outbound email transport surfaced as `ctx.mailer`. Procedures that
+     * touch mail (auth.mailer.testSend, future invite-email, etc.)
+     * read from there; tests pass a capturing implementation here so
+     * they can assert what was sent.
+     */
+    readonly mailer?: Mailer;
+    /**
+     * Site name surfaced as `ctx.siteName` — used by email-composing
+     * procedures (email change, magic-link RPC paths) to brand the
+     * outgoing message. Mirrors the operator-set
+     * `auth.magicLink.siteName`. Default undefined; tests that
+     * exercise email composition pass a fixture name here.
+     */
+    readonly siteName?: string;
+}
+export interface AuthenticatedHarnessOptions extends BaseRpcHarnessOptions {
+    readonly authAs: UserRole;
+}
+export interface RpcHarnessBase<TUser extends User | null> {
+    readonly db: TestDb;
+    readonly hooks: HookRegistry;
+    readonly plugins: PluginRegistry;
+    readonly env: PlumixEnv;
+    readonly context: AppContext;
+    readonly client: RouterClient<typeof appRouter>;
+    readonly user: TUser;
+    readonly factory: Factories;
+    readonly spyAction: <TName extends ActionName>(name: TName) => ActionSpy<ActionArgs<TName>>;
+    readonly spyFilter: <TName extends FilterName>(name: TName) => FilterSpy<FilterInput<TName>, FilterRest<TName>>;
+    /**
+     * Return a new harness bound to the given user (or freshly seeded user of
+     * the given role). The underlying db / hooks / plugins / env are shared,
+     * so state survives the swap — use this for tests that exercise multiple
+     * roles in a single scenario.
+     */
+    readonly actingAs: (userOrRole: User | UserRole) => Promise<AuthenticatedRpcHarness>;
+}
+export type RpcHarness = RpcHarnessBase<User | null>;
+export type AuthenticatedRpcHarness = RpcHarnessBase<User>;
+export declare function createRpcHarness(options: AuthenticatedHarnessOptions): Promise<AuthenticatedRpcHarness>;
+export declare function createRpcHarness(options?: BaseRpcHarnessOptions): Promise<RpcHarness>;
+export {};
+//# sourceMappingURL=rpc.d.ts.map

package/dist/test/rpc.d.ts.map

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

package/dist/test/rpc.js

@@ -0,0 +1,91 @@
+import { createRouterClient } from "@orpc/server";
+import { coreBlocks, coreMarks, createBlockRegistry } from "@plumix/blocks";
+import { SESSION_COOKIE_NAME } from "../auth/cookies.js";
+import { createSession } from "../auth/sessions.js";
+import { createAppContext } from "../context/app.js";
+import { HookRegistry as HookRegistryImpl } from "../hooks/registry.js";
+import { createPluginRegistry } from "../plugin/manifest.js";
+import { appRouter } from "../rpc/router.js";
+import { factoriesFor, userFactory } from "./factories.js";
+import { createTestDb } from "./harness.js";
+import { spyAction, spyFilter } from "./spies.js";
+const noop = () => undefined;
+const silentLogger = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+};
+function buildContext(db, env, hooks, plugins, blocks, marks, request, oauthProviders, authenticator, mailer, siteName) {
+    return createAppContext({
+        db,
+        env,
+        request,
+        hooks,
+        plugins,
+        blocks,
+        marks,
+        logger: silentLogger,
+        oauthProviders,
+        authenticator,
+        mailer,
+        siteName,
+    });
+}
+function unauthenticatedRequest() {
+    return new Request("https://cms.example/_plumix/rpc", { method: "POST" });
+}
+async function authenticatedRequest(db, userId) {
+    const { token } = await createSession(db, { userId });
+    return new Request("https://cms.example/_plumix/rpc", {
+        method: "POST",
+        headers: { cookie: `${SESSION_COOKIE_NAME}=${token}` },
+    });
+}
+function assemble(db, env, hooks, plugins, blocks, marks, request, user, oauthProviders, authenticator, mailer, siteName) {
+    const context = buildContext(db, env, hooks, plugins, blocks, marks, request, oauthProviders, authenticator, mailer, siteName);
+    const client = createRouterClient(appRouter, { context });
+    const harness = {
+        db,
+        env,
+        hooks,
+        plugins,
+        context,
+        client,
+        user,
+        factory: factoriesFor(db),
+        spyAction: (name) => spyAction(hooks, name),
+        spyFilter: (name) => spyFilter(hooks, name),
+        actingAs: async (userOrRole) => {
+            const targetUser = typeof userOrRole === "string"
+                ? await userFactory.transient({ db }).create({ role: userOrRole })
+                : userOrRole;
+            const req = await authenticatedRequest(db, targetUser.id);
+            return assemble(db, env, hooks, plugins, blocks, marks, req, targetUser, oauthProviders, authenticator, mailer, siteName);
+        },
+    };
+    return harness;
+}
+export async function createRpcHarness(options = {}) {
+    const db = await createTestDb();
+    const hooks = options.hooks ?? new HookRegistryImpl();
+    const plugins = options.plugins ?? createPluginRegistry();
+    const env = options.env ?? {};
+    const oauthProviders = options.oauthProviders ?? [];
+    // Build the same default registries `buildApp` would so the RPC
+    // harness exercises validation against the real core specs.
+    const pluginBlockSpecs = Array.from(plugins.blockSpecs.values()).map(({ spec }) => spec);
+    const pluginMarkSpecs = Array.from(plugins.markSpecs.values()).map(({ spec }) => spec);
+    const blocks = createBlockRegistry([...coreBlocks, ...pluginBlockSpecs]);
+    const marks = [...coreMarks, ...pluginMarkSpecs];
+    if (!options.request && options.authAs) {
+        const user = await userFactory
+            .transient({ db })
+            .create({ role: options.authAs });
+        const request = await authenticatedRequest(db, user.id);
+        return assemble(db, env, hooks, plugins, blocks, marks, request, user, oauthProviders, options.authenticator, options.mailer, options.siteName);
+    }
+    const request = options.request ?? unauthenticatedRequest();
+    return assemble(db, env, hooks, plugins, blocks, marks, request, null, oauthProviders, options.authenticator, options.mailer, options.siteName);
+}
+//# sourceMappingURL=rpc.js.map

package/dist/test/rpc.js.map

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

package/dist/test/spies.d.ts

@@ -0,0 +1,68 @@
+import type { HookRegistry } from "../hooks/registry.js";
+import type { ActionArgs, ActionName, FilterInput, FilterName, FilterRest } from "../hooks/types.js";
+export interface ActionCall<TArgs extends readonly unknown[]> {
+    readonly args: TArgs;
+}
+export interface FilterCall<TValue, TRest extends readonly unknown[]> {
+    readonly input: TValue;
+    readonly rest: TRest;
+}
+interface SpyBaseReadonly<TCall> {
+    readonly called: boolean;
+    readonly callCount: number;
+    readonly calls: readonly TCall[];
+}
+export interface ActionSpy<TArgs extends readonly unknown[]> extends SpyBaseReadonly<ActionCall<TArgs>> {
+    readonly lastArgs: TArgs | undefined;
+    assertCalled(): ActionSpy<TArgs>;
+    assertCalledOnce(): ActionSpy<TArgs>;
+    assertCalledTimes(n: number): ActionSpy<TArgs>;
+    assertNotCalled(): ActionSpy<TArgs>;
+    assertCalledWith(matcher: (...args: TArgs) => boolean | void): ActionSpy<TArgs>;
+    reset(): void;
+}
+export interface FilterSpy<TValue, TRest extends readonly unknown[]> extends SpyBaseReadonly<FilterCall<TValue, TRest>> {
+    readonly lastInput: TValue | undefined;
+    assertCalled(): FilterSpy<TValue, TRest>;
+    assertCalledOnce(): FilterSpy<TValue, TRest>;
+    assertCalledTimes(n: number): FilterSpy<TValue, TRest>;
+    assertNotCalled(): FilterSpy<TValue, TRest>;
+    assertCalledWith(matcher: (input: TValue, ...rest: TRest) => boolean | void): FilterSpy<TValue, TRest>;
+    /**
+     * Replace the pass-through with a transform. The spy still records every
+     * call, but the filter chain now sees the transform's return value.
+     */
+    override(transform: (input: TValue, ...rest: TRest) => TValue | Promise<TValue>): void;
+}
+/**
+ * Install a recording listener on the named action. Captures every call's
+ * args for later assertion. Adding the spy is non-destructive — other
+ * listeners continue to run normally.
+ */
+export declare function spyAction<TName extends ActionName>(hooks: HookRegistry, name: TName): ActionSpy<ActionArgs<TName>>;
+/**
+ * Install a recording filter on the named hook. By default it's a
+ * pass-through; call `.override(fn)` to transform the value. Still records
+ * every invocation regardless.
+ *
+ * @remarks
+ * Identity note: the hook registry `structuredClone`s each filter input
+ * before passing it to listeners, so `spy.calls[i].input` is a clone, not
+ * the caller-supplied reference. Use equality matchers
+ * (`deepEqual` / `toEqual` / `toMatchObject`) — not identity / `toBe`.
+ */
+export declare function spyFilter<TName extends FilterName>(hooks: HookRegistry, name: TName): FilterSpy<FilterInput<TName>, FilterRest<TName>>;
+/**
+ * Assert that a promise rejects with a specific error code (and optionally
+ * matches a partial data shape). Replaces the widely-copied
+ * `.rejects.toMatchObject({ code, data })` idiom.
+ *
+ * Runner-agnostic — throws plain Errors, so it works under vitest, jest,
+ * node:test, bun test, or anything that surfaces thrown errors as failures.
+ */
+export declare function expectError(promise: Promise<unknown>, expected: {
+    readonly code: string;
+    readonly data?: unknown;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=spies.d.ts.map

package/dist/test/spies.d.ts.map

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

package/dist/test/spies.js

@@ -0,0 +1,144 @@
+import { partialMatch } from "./match.js";
+/**
+ * Shared assertion / state helpers for both spy flavours. `self` is a
+ * thunk so the methods return the concrete spy type for chaining — the
+ * base only knows how to count and reset the call array.
+ */
+function buildSpyBase(label, calls, self) {
+    return {
+        get called() {
+            return calls.length > 0;
+        },
+        get callCount() {
+            return calls.length;
+        },
+        get calls() {
+            return calls;
+        },
+        assertCalled() {
+            if (calls.length === 0) {
+                throw new Error(`${label}: expected to be called, was not`);
+            }
+            return self();
+        },
+        assertCalledOnce() {
+            if (calls.length !== 1) {
+                throw new Error(`${label}: expected exactly 1 call, got ${calls.length}`);
+            }
+            return self();
+        },
+        assertCalledTimes(n) {
+            if (calls.length !== n) {
+                throw new Error(`${label}: expected ${n} calls, got ${calls.length}`);
+            }
+            return self();
+        },
+        assertNotCalled() {
+            if (calls.length > 0) {
+                throw new Error(`${label}: expected no calls, got ${calls.length}`);
+            }
+            return self();
+        },
+        reset() {
+            calls.length = 0;
+        },
+    };
+}
+/**
+ * Install a recording listener on the named action. Captures every call's
+ * args for later assertion. Adding the spy is non-destructive — other
+ * listeners continue to run normally.
+ */
+export function spyAction(hooks, name) {
+    const calls = [];
+    hooks.addAction(name, ((...args) => {
+        calls.push({ args });
+    }));
+    const label = `spyAction(${name})`;
+    const spy = {
+        ...buildSpyBase(label, calls, () => spy),
+        get lastArgs() {
+            return calls[calls.length - 1]?.args;
+        },
+        assertCalledWith(matcher) {
+            for (const call of calls) {
+                const result = matcher(...call.args);
+                if (result === true || result === undefined)
+                    return spy;
+            }
+            throw new Error(`${label}: no call matched the supplied matcher`);
+        },
+    };
+    return spy;
+}
+/**
+ * Install a recording filter on the named hook. By default it's a
+ * pass-through; call `.override(fn)` to transform the value. Still records
+ * every invocation regardless.
+ *
+ * @remarks
+ * Identity note: the hook registry `structuredClone`s each filter input
+ * before passing it to listeners, so `spy.calls[i].input` is a clone, not
+ * the caller-supplied reference. Use equality matchers
+ * (`deepEqual` / `toEqual` / `toMatchObject`) — not identity / `toBe`.
+ */
+export function spyFilter(hooks, name) {
+    const calls = [];
+    let transform = null;
+    hooks.addFilter(name, (async (input, ...rest) => {
+        calls.push({ input, rest });
+        if (transform)
+            return transform(input, ...rest);
+        return input;
+    }));
+    const label = `spyFilter(${name})`;
+    const spy = {
+        ...buildSpyBase(label, calls, () => spy),
+        get lastInput() {
+            return calls[calls.length - 1]?.input;
+        },
+        assertCalledWith(matcher) {
+            for (const call of calls) {
+                const result = matcher(call.input, ...call.rest);
+                if (result === true || result === undefined)
+                    return spy;
+            }
+            throw new Error(`${label}: no call matched the supplied matcher`);
+        },
+        override(fn) {
+            transform = fn;
+        },
+    };
+    return spy;
+}
+/**
+ * Assert that a promise rejects with a specific error code (and optionally
+ * matches a partial data shape). Replaces the widely-copied
+ * `.rejects.toMatchObject({ code, data })` idiom.
+ *
+ * Runner-agnostic — throws plain Errors, so it works under vitest, jest,
+ * node:test, bun test, or anything that surfaces thrown errors as failures.
+ */
+export async function expectError(promise, expected) {
+    let caught = undefined;
+    try {
+        await promise;
+    }
+    catch (error) {
+        caught = error;
+    }
+    if (caught === undefined) {
+        throw new Error(`expectError: expected rejection with code="${expected.code}", promise resolved`);
+    }
+    const actualCode = caught.code;
+    if (actualCode !== expected.code) {
+        throw new Error(`expectError: expected code="${expected.code}", got "${String(actualCode)}"`);
+    }
+    if (expected.data !== undefined) {
+        const actualData = caught.data;
+        if (!partialMatch(actualData, expected.data)) {
+            throw new Error(`expectError: data did not match — expected ${JSON.stringify(expected.data)}, got ${JSON.stringify(actualData)}`);
+        }
+    }
+}
+//# sourceMappingURL=spies.js.map

package/dist/test/spies.js.map

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

package/dist/theme-errors.d.ts

@@ -0,0 +1,37 @@
+type ThemeRegistrationCode = "missing_theme" | "missing_index_template" | "legacy_template_deps_shape" | "theme_dep_function_form" | "document_invalid_link" | "document_invalid_script" | "invalid_template";
+export declare class ThemeRegistrationError extends Error {
+    readonly code: ThemeRegistrationCode;
+    private constructor();
+    static missingTheme(): ThemeRegistrationError;
+    static missingIndexTemplate(): ThemeRegistrationError;
+    static legacyTemplateDepsShape(): ThemeRegistrationError;
+    static themeDepFunctionForm(kind: string): ThemeRegistrationError;
+    static documentInvalidLink(ctx: {
+        index: number;
+        slot?: string;
+    }): ThemeRegistrationError;
+    static invalidTemplate(ctx: {
+        slot: string;
+    }): ThemeRegistrationError;
+    static documentInvalidScript(ctx: {
+        index: number;
+        slot?: string;
+    }): ThemeRegistrationError;
+}
+export declare class ThemeError extends Error {
+    readonly code: "invalid_token_slug" | "invalid_token_value";
+    readonly group: string;
+    readonly slug: string;
+    private constructor();
+    static invalidTokenSlug(ctx: {
+        group: string;
+        slug: string;
+    }): ThemeError;
+    static invalidTokenValue(ctx: {
+        group: string;
+        slug: string;
+        value: string;
+    }): ThemeError;
+}
+export {};
+//# sourceMappingURL=theme-errors.d.ts.map

package/dist/theme-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-errors.d.ts","sourceRoot":"","sources":["../src/theme-errors.ts"],"names":[],"mappings":"AAAA,KAAK,qBAAqB,GACtB,eAAe,GACf,wBAAwB,GACxB,4BAA4B,GAC5B,yBAAyB,GACzB,uBAAuB,GACvB,yBAAyB,GACzB,kBAAkB,CAAC;AAEvB,qBAAa,sBAAuB,SAAQ,KAAK;IAK/C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAErC,OAAO;IAKP,MAAM,CAAC,YAAY,IAAI,sBAAsB;IAU7C,MAAM,CAAC,oBAAoB,IAAI,sBAAsB;IASrD,MAAM,CAAC,uBAAuB,IAAI,sBAAsB;IAWxD,MAAM,CAAC,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB;IAUjE,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE;QAC9B,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,sBAAsB;IAa1B,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,sBAAsB;IAWrE,MAAM,CAAC,qBAAqB,CAAC,GAAG,EAAE;QAChC,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,sBAAsB;CAY3B;AAED,qBAAa,UAAW,SAAQ,KAAK;IAKnC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,CAAC;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,OAAO;IAYP,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU;IAYzE,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE;QAC5B,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,UAAU;CAYf"}

package/dist/theme-errors.js

@@ -0,0 +1,87 @@
+export class ThemeRegistrationError extends Error {
+    static {
+        ThemeRegistrationError.prototype.name = "ThemeRegistrationError";
+    }
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+    static missingTheme() {
+        return new ThemeRegistrationError("missing_theme", `Plumix config requires a \`theme\`. Every app renders public routes ` +
+            `through a theme — there is no inline-HTML fallback. Define one with ` +
+            `\`defineTheme({ templates: { index: …, … } })\` and pass it to ` +
+            `\`plumix({ … , theme })\`.`);
+    }
+    static missingIndexTemplate() {
+        return new ThemeRegistrationError("missing_index_template", `Theme registration: \`templates.index\` is required. Every theme ` +
+            `must declare an \`index\` template — it is the final fallback the ` +
+            `template hierarchy walks to when no more-specific template matches.`);
+    }
+    static legacyTemplateDepsShape() {
+        return new ThemeRegistrationError("legacy_template_deps_shape", `Theme registration: \`templateDeps: { ... }\` is no longer accepted. ` +
+            `Lift dep kinds to the flat root of \`defineTheme\` instead — e.g. ` +
+            `\`defineTheme({ menus: ["primary"], settings: ["general"], templates: { ... } })\`. ` +
+            `Templates compose via the array (replace) or function (extend) form ` +
+            `per kind; see #614.`);
+    }
+    static themeDepFunctionForm(kind) {
+        return new ThemeRegistrationError("theme_dep_function_form", `Theme registration: dep kind \`${kind}\` was declared as a function. ` +
+            `The function form means "given the parent, return the next" — but the ` +
+            `theme root has no parent. Use a plain array at the theme level; the ` +
+            `function form is for per-template extension (see #614).`);
+    }
+    static documentInvalidLink(ctx) {
+        const source = ctx.slot
+            ? `template \`${ctx.slot}\` document fragment`
+            : "`theme:document` filter chain";
+        return new ThemeRegistrationError("document_invalid_link", `${source} produced a \`link[${ctx.index}]\` entry without a \`rel\` ` +
+            `attribute. Every \`<link>\` in the document manifest must declare ` +
+            `a \`rel\` — browsers ignore unkeyed link tags and the renderer ` +
+            `would emit invalid HTML.`);
+    }
+    static invalidTemplate(ctx) {
+        return new ThemeRegistrationError("invalid_template", `Theme registration: templates.${ctx.slot} must be either a plain ` +
+            `function (legacy form) or a Template built via \`defineTemplate({ ` +
+            `render: ... })\`. A hand-written \`{ render }\` literal that ` +
+            `didn't go through the factory is rejected so future deps / ` +
+            `document-fragment fields don't get silently ignored.`);
+    }
+    static documentInvalidScript(ctx) {
+        const source = ctx.slot
+            ? `template \`${ctx.slot}\` document fragment`
+            : "`theme:document` filter chain";
+        return new ThemeRegistrationError("document_invalid_script", `${source} produced a \`script[${ctx.index}]\` entry with neither ` +
+            `\`src\` nor inline content (\`children\` / ` +
+            `\`dangerouslySetInnerHTML\`). Scripts must reference a source URL ` +
+            `or carry an inline body — an empty \`<script>\` tag is dead weight.`);
+    }
+}
+export class ThemeError extends Error {
+    static {
+        ThemeError.prototype.name = "ThemeError";
+    }
+    code;
+    group;
+    slug;
+    constructor(code, message, group, slug) {
+        super(message);
+        this.code = code;
+        this.group = group;
+        this.slug = slug;
+    }
+    static invalidTokenSlug(ctx) {
+        return new ThemeError("invalid_token_slug", `defineTheme: tokens.${ctx.group} slug ${JSON.stringify(ctx.slug)} is invalid. ` +
+            `Token slugs must match /^[a-z][a-z0-9-]*$/ — they are concatenated into CSS ` +
+            `custom-property names, so whitespace or CSS-delimiter characters would break ` +
+            `themes that bind them.`, ctx.group, ctx.slug);
+    }
+    static invalidTokenValue(ctx) {
+        return new ThemeError("invalid_token_value", `defineTheme: tokens.${ctx.group}.${ctx.slug} value ${JSON.stringify(ctx.value)} ` +
+            `contains characters that would break out of a CSS declaration value ` +
+            `(semicolons, braces, comment delimiters, or newlines). Themes embed token ` +
+            `values via CSS \`var(...)\` references, so any of those bytes lets the token ` +
+            `rewrite arbitrary rules.`, ctx.group, ctx.slug);
+    }
+}
+//# sourceMappingURL=theme-errors.js.map

package/dist/theme-errors.js.map

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

package/dist/theme.d.ts

@@ -0,0 +1,91 @@
+import type { ComponentType, JSX } from "react";
+import type { ShortcodeSpec, ThemeBreakpoints, ThemeTokens } from "@plumix/blocks";
+import type { ArchiveData, ErrorData, FrontPageData, SearchData, SingleData, TaxonomyData } from "./route/render/resolved-entry.js";
+import type { Template, TemplateDepDeclarations } from "./template.js";
+declare module "./hooks/types.js" {
+    interface FilterRegistry {
+        "theme:document": (manifest: DocumentManifest) => DocumentManifest | Promise<DocumentManifest>;
+    }
+}
+/**
+ * Discriminated union of every data shape a template can receive. Per-kind
+ * templates (`single`, `archive`, …) narrow via the registry; `index`
+ * receives the union and discriminates at runtime (e.g. `"entry" in data`).
+ */
+export type TemplateData = SingleData | ArchiveData | TaxonomyData | FrontPageData | SearchData | ErrorData;
+export type TemplateComponent<Data> = ComponentType<{
+    readonly data: Data;
+}>;
+export type TemplateEntry<Data extends TemplateData> = TemplateComponent<Data> | Template<Data>;
+type DynamicTemplateEntry = TemplateEntry<SingleData> | TemplateEntry<ArchiveData> | TemplateEntry<TaxonomyData> | TemplateEntry<FrontPageData> | TemplateEntry<SearchData> | TemplateEntry<ErrorData> | TemplateEntry<TemplateData>;
+/**
+ * Strip React-isms that don't belong in HTML attribute descriptors:
+ * `key`/`ref` are React infrastructure; `on*` handlers don't apply
+ * to SSR'd strings; `children` and `dangerouslySetInnerHTML` are kept
+ * only for `<script>` (inline content).
+ */
+type DocumentTag<T extends keyof JSX.IntrinsicElements> = Omit<JSX.IntrinsicElements[T], "key" | "ref" | `on${string}`>;
+export type DocumentLink = Omit<DocumentTag<"link">, "children" | "dangerouslySetInnerHTML">;
+export type DocumentMeta = Omit<DocumentTag<"meta">, "children" | "dangerouslySetInnerHTML">;
+export type DocumentScript = Omit<DocumentTag<"script">, "children" | "dangerouslySetInnerHTML"> & {
+    readonly position?: "headStart" | "headEnd" | "bodyStart" | "bodyEnd";
+    readonly children?: string;
+    readonly dangerouslySetInnerHTML?: {
+        readonly __html: string;
+    };
+};
+export interface DocumentManifest {
+    readonly html?: Omit<DocumentTag<"html">, "children" | "dangerouslySetInnerHTML">;
+    readonly body?: Omit<DocumentTag<"body">, "children" | "dangerouslySetInnerHTML">;
+    readonly link?: readonly DocumentLink[];
+    readonly meta?: readonly DocumentMeta[];
+    readonly script?: readonly DocumentScript[];
+    readonly title?: string;
+    readonly titleTemplate?: string | ((title: string | undefined) => string);
+}
+export interface TemplateRegistry {
+    readonly index: TemplateEntry<TemplateData>;
+    readonly single?: TemplateEntry<SingleData>;
+    readonly singular?: TemplateEntry<SingleData>;
+    readonly page?: TemplateEntry<SingleData>;
+    readonly archive?: TemplateEntry<ArchiveData>;
+    readonly taxonomy?: TemplateEntry<TaxonomyData>;
+    readonly category?: TemplateEntry<TaxonomyData>;
+    readonly tag?: TemplateEntry<TaxonomyData>;
+    readonly "front-page"?: TemplateEntry<FrontPageData>;
+    readonly home?: TemplateEntry<FrontPageData>;
+    readonly search?: TemplateEntry<SearchData>;
+    readonly "404"?: TemplateEntry<ErrorData>;
+    readonly "500"?: TemplateEntry<ErrorData>;
+    readonly [key: string]: DynamicTemplateEntry | undefined;
+}
+export interface ThemeDescriptor extends TemplateDepDeclarations {
+    readonly templates: TemplateRegistry;
+    readonly document?: DocumentManifest;
+    readonly tokens?: ThemeTokens;
+    /**
+     * Responsive breakpoints (max-width px) for the `tablet`/`mobile` buckets.
+     * Feed both the SSR style emitter's @media maxima and the editor's
+     * device-switch canvas widths, so preview equals shipped. Defaults to
+     * `DEFAULT_BREAKPOINTS` (991/640) when unspecified.
+     */
+    readonly breakpoints?: ThemeBreakpoints;
+    /**
+     * Shortcodes the theme declares without a setup hook (like `tokens`).
+     * These take precedence over plugin and core shortcodes of the same tag
+     * — the most site-specific layer wins.
+     */
+    readonly shortcodes?: readonly ShortcodeSpec[];
+    /**
+     * Paths (relative to the project root or aliased) to CSS / asset files
+     * that should ship as client bundles. Mirror of Nuxt's `css: []` — the
+     * strings never enter jiti's module graph; the plumix Vite plugin
+     * generates a synthetic client entry that imports each path so Vite
+     * resolves them through its normal graph and emits hashed bundles.
+     */
+    readonly css?: readonly string[];
+}
+export declare function defineTheme(descriptor: ThemeDescriptor): ThemeDescriptor;
+export declare function validateDocumentManifest(manifest: DocumentManifest, slot?: string): void;
+export {};
+//# sourceMappingURL=theme.d.ts.map