@weasel-js/forge 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @weasel-js/forge
+
+A component workshop built on labkit. It reads Storybook's story files and
+renders each story in its own frame document; the story's controls, state,
+undo and snapshots live in a labkit trial beside it, so two settings of one
+component can be compared side by side.
+
+Direction: `docs/superpowers/specs/2026-09-13-forge-design.md`.
+
+## Config modules
+
+The vite plugin takes two optional config modules, one per realm, because the
+workshop page and each frame document are separate documents:
+
+- `frameConfig` default-exports `defineFrameConfig({...})`: decorators around
+  every story, `applyGlobals` for what a global does to the frame document,
+  `cssVarsScope`, and `parameters`, the project-wide CSF parameters that
+  Storybook keeps in `preview`. Only frame documents import it, so its CSS
+  stays off the workshop page.
+- `shellConfig` default-exports `defineShellConfig({...})`: lab chrome, control
+  renderers, and global declarations. Only the workshop page imports it.
+
+```ts
+forge({ stories: ['src/**/*.stories.tsx'], frameConfig: 'forge.frame.tsx', shellConfig: 'forge.shell.tsx' });
+```
+
+## Story tests
+
+`forgeTest` from `@weasel-js/forge/vite` runs every story as a vitest browser
+test: each story renders through forge's frame with its defaults, plays, and
+fails on any fault. Pass it the same `frameConfig`. It needs vitest 4 in browser mode with a provider, such as
+`@vitest/browser-playwright`. This repo runs it with
+`npm run test:stories:forge`, not in CI.

package/dist/FrameController-Ba3LaWfq.d.ts

@@ -0,0 +1,196 @@
+import { BranchAnnotations, Annotations, ConfigSchema } from '@weasel-js/labkit/config';
+import { ReactNode } from 'react';
+
+interface Channel<In, Out> {
+    send(msg: Out): void;
+    on(fn: (msg: In) => void): () => void;
+    close(): void;
+}
+
+interface SectionDescription {
+    label: string;
+    collapsed?: boolean;
+}
+type DescribedEntry = {
+    branch: true;
+    annotations: BranchAnnotations;
+    section?: SectionDescription;
+    conditional: boolean;
+    children: DescribedShape;
+} | {
+    branch: false;
+    kind: string | null;
+    default: unknown;
+    annotations: Annotations;
+    section?: SectionDescription;
+    conditional: boolean;
+    validated: boolean;
+    /** The node draws its own row with `.render`, which stays in the frame. */
+    customControl: boolean;
+};
+type DescribedShape = {
+    [key: string]: DescribedEntry;
+};
+/** A story's `f.schema` as structured-clone data. */
+interface SchemaDescription {
+    nodes: DescribedShape;
+}
+
+type Globals = Readonly<Record<string, unknown>>;
+type Layout = 'centered' | 'padded' | 'fullscreen';
+interface Viewport {
+    width: number;
+    height: number;
+}
+type FaultPhase = 'import' | 'render' | 'play' | 'protocol';
+/** One custom property as the frame found it. */
+interface CssVarReport {
+    name: string;
+    value: string;
+    /** Whether a `vars.set` override is in force on it. */
+    overridden: boolean;
+}
+/** Visibility and validation answers, keyed by the config they were computed for. */
+interface ConfigAnswers {
+    /** `stableStringify(config)` of the config the frame evaluated. */
+    configKey: string;
+    hidden: string[];
+    errors: Record<string, string[]>;
+}
+type ToFrame = {
+    type: 'init';
+    config: unknown;
+    state: unknown;
+    globals: Globals;
+} | {
+    type: 'config';
+    config: unknown;
+} | {
+    type: 'state';
+    state: unknown;
+} | {
+    type: 'globals';
+    globals: Globals;
+} | {
+    type: 'vars.set';
+    name: string;
+    value: string | null;
+} | {
+    type: 'play';
+};
+type FromFrame = {
+    type: 'ready';
+    schema: SchemaDescription;
+    layout: Layout;
+    viewport: Viewport | null;
+} | {
+    type: 'answers';
+    answers: ConfigAnswers;
+} | {
+    type: 'setConfig';
+    path: string;
+    value: unknown;
+} | {
+    type: 'setState';
+    state: unknown;
+} | {
+    type: 'size';
+    width: number;
+    height: number;
+} | {
+    type: 'vars';
+    vars: CssVarReport[];
+} | {
+    type: 'played';
+    ok: boolean;
+    message?: string;
+}
+/** `seq`, on a render fault only: how many `init`/`config`/`state`/`globals` messages the frame had received. */
+ | {
+    type: 'fault';
+    phase: FaultPhase;
+    message: string;
+    stack?: string;
+    seq?: number;
+};
+
+interface StoryContext<C = unknown, S = unknown> {
+    config: C;
+    setConfig: (path: string, value: unknown) => void;
+    state: S;
+    setState: (next: S | ((prev: S) => S)) => void;
+    globals: Globals;
+    title: string;
+    name: string;
+}
+interface PlayContext<C = unknown> {
+    canvasElement: HTMLElement;
+    config: C;
+    globals: Globals;
+}
+type Decorator = (story: () => ReactNode, ctx: StoryContext) => ReactNode;
+interface MetaSpec {
+    title?: string;
+    decorators?: Decorator[];
+    layout?: Layout;
+}
+interface StorySpec<C = Record<string, never>, S = undefined> {
+    name?: string;
+    config?: ConfigSchema<C>;
+    state?: (config: C) => S;
+    render: (ctx: StoryContext<C, S>) => ReactNode;
+    decorators?: Decorator[];
+    layout?: Layout;
+    viewport?: Viewport;
+    play?: (ctx: PlayContext<C>) => void | Promise<void>;
+}
+/** One story, normalized — what both the native and CSF loaders produce. */
+interface LoadedStory {
+    id: string;
+    title: string;
+    name: string;
+    exportName: string;
+    config: ConfigSchema<unknown>;
+    initialState: ((config: unknown) => unknown) | null;
+    render: (ctx: StoryContext) => ReactNode;
+    /** Innermost first: the story's own, then the meta's. Global decorators are added by the frame. */
+    decorators: Decorator[];
+    layout: Layout;
+    viewport: Viewport | null;
+    play: ((ctx: PlayContext) => void | Promise<void>) | null;
+}
+/** One story as the index knows it, before its module is loaded. */
+interface IndexEntry {
+    id: string;
+    title: string;
+    name: string;
+    exportName: string;
+    /** Absolute path of the story file. */
+    file: string;
+}
+
+interface FrameSetup {
+    /** Wraps every story, outermost; receives the globals. From the frame config (`frameConfig`). */
+    decorators?: Decorator[];
+    /** Applies globals to the frame document — theme mode, fonts. */
+    applyGlobals?: (globals: Globals, root: HTMLElement) => void;
+    /**
+     * The elements a CSS variable override is declared on; `:root` by default. An override has to be declared on
+     * whichever element declares the token itself — a theme wrapper, say — or that element's own value wins.
+     */
+    cssVarsScope?: string;
+    /** Project-wide CSF parameters, Storybook's preview `parameters`: under each meta's and story's. */
+    parameters?: Record<string, unknown>;
+}
+interface StartFrameOptions {
+    story: LoadedStory;
+    channel: Channel<ToFrame, FromFrame>;
+    container: HTMLElement;
+    setup?: FrameSetup;
+}
+/** Sends `ready`, then renders the story on `init` and keeps it in step. Returns a stop function. */
+declare function startFrame({ story, channel, container, setup }: StartFrameOptions): () => void;
+/** Reports an import failure — there is no story to start. */
+declare function reportImportFault(channel: Channel<ToFrame, FromFrame>, error: unknown): void;
+
+export { type Decorator as D, type FrameSetup as F, type IndexEntry as I, type LoadedStory as L, type MetaSpec as M, type PlayContext as P, type StorySpec as S, type StoryContext as a, type StartFrameOptions as b, type FromFrame as c, reportImportFault as r, startFrame as s };

package/dist/chunk-2GXKNXTJ.js

@@ -0,0 +1,15 @@
+// src/story/define.ts
+var NATIVE = /* @__PURE__ */ Symbol.for("weaselforge.native");
+function meta(spec) {
+  return Object.assign({}, spec, { [NATIVE]: "meta" });
+}
+function story(spec) {
+  return Object.assign({}, spec, { [NATIVE]: "story" });
+}
+function isNative(value, kind) {
+  return !!value && typeof value === "object" && value[NATIVE] === kind;
+}
+
+export { isNative, meta, story };
+//# sourceMappingURL=chunk-2GXKNXTJ.js.map
+//# sourceMappingURL=chunk-2GXKNXTJ.js.map

package/dist/chunk-2GXKNXTJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/story/define.ts"],"names":[],"mappings":";AAEO,IAAM,MAAA,mBAAS,MAAA,CAAO,GAAA,CAAI,oBAAoB,CAAA;AAE9C,SAAS,KAAK,IAAA,EAA0B;AAC7C,EAAA,OAAO,MAAA,CAAO,MAAA,CAAO,EAAC,EAAG,IAAA,EAAM,EAAE,CAAC,MAAM,GAAG,MAAA,EAAiB,CAAA;AAC9D;AAEO,SAAS,MAAgD,IAAA,EAAwC;AACtG,EAAA,OAAO,MAAA,CAAO,MAAA,CAAO,EAAC,EAAG,IAAA,EAAM,EAAE,CAAC,MAAM,GAAG,OAAA,EAAkB,CAAA;AAC/D;AAEO,SAAS,QAAA,CAAS,OAAgB,IAAA,EAAiC;AACxE,EAAA,OAAO,CAAC,CAAC,KAAA,IAAS,OAAO,UAAU,QAAA,IAAa,KAAA,CAAkC,MAAM,CAAA,KAAM,IAAA;AAChG","file":"chunk-2GXKNXTJ.js","sourcesContent":["import type { MetaSpec, StorySpec } from './types';\n\nexport const NATIVE = Symbol.for('weaselforge.native');\n\nexport function meta(spec: MetaSpec): MetaSpec {\n  return Object.assign({}, spec, { [NATIVE]: 'meta' as const });\n}\n\nexport function story<C = Record<string, never>, S = undefined>(spec: StorySpec<C, S>): StorySpec<C, S> {\n  return Object.assign({}, spec, { [NATIVE]: 'story' as const });\n}\n\nexport function isNative(value: unknown, kind: 'meta' | 'story'): boolean {\n  return !!value && typeof value === 'object' && (value as Record<symbol, unknown>)[NATIVE] === kind;\n}\n"]}

package/dist/chunk-IOBG7GZQ.js

@@ -0,0 +1,13 @@
+// src/protocol/messages.ts
+var PROTOCOL_VERSION = 1;
+var PORT_HANDOFF = "weaselforge:port";
+function stableStringify(value) {
+  return JSON.stringify(
+    value,
+    (_key, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : 1)) : v
+  );
+}
+
+export { PORT_HANDOFF, PROTOCOL_VERSION, stableStringify };
+//# sourceMappingURL=chunk-IOBG7GZQ.js.map
+//# sourceMappingURL=chunk-IOBG7GZQ.js.map

package/dist/chunk-IOBG7GZQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol/messages.ts"],"names":[],"mappings":";AAEO,IAAM,gBAAA,GAAmB;AAmDzB,IAAM,YAAA,GAAe;AAGrB,SAAS,gBAAgB,KAAA,EAAwB;AACtD,EAAA,OAAO,IAAA,CAAK,SAAA;AAAA,IAAU,KAAA;AAAA,IAAO,CAAC,IAAA,EAAM,CAAA,KAClC,CAAA,IAAK,OAAO,CAAA,KAAM,QAAA,IAAY,CAAC,KAAA,CAAM,OAAA,CAAQ,CAAC,CAAA,GAC1C,OAAO,WAAA,CAAY,MAAA,CAAO,OAAA,CAAQ,CAAC,CAAA,CAAE,IAAA,CAAK,CAAC,CAAC,CAAC,CAAA,EAAG,CAAC,CAAC,CAAA,KAAO,CAAA,GAAI,CAAA,GAAI,EAAA,GAAK,CAAE,CAAC,CAAA,GACzE;AAAA,GACN;AACF","file":"chunk-IOBG7GZQ.js","sourcesContent":["import type { SchemaDescription } from './schema';\n\nexport const PROTOCOL_VERSION = 1;\n\nexport type Globals = Readonly<Record<string, unknown>>;\nexport type Layout = 'centered' | 'padded' | 'fullscreen';\nexport interface Viewport {\n  width: number;\n  height: number;\n}\nexport type FaultPhase = 'import' | 'render' | 'play' | 'protocol';\n\n/** One custom property as the frame found it. */\nexport interface CssVarReport {\n  name: string;\n  value: string;\n  /** Whether a `vars.set` override is in force on it. */\n  overridden: boolean;\n}\n\n/** Visibility and validation answers, keyed by the config they were computed for. */\nexport interface ConfigAnswers {\n  /** `stableStringify(config)` of the config the frame evaluated. */\n  configKey: string;\n  hidden: string[];\n  errors: Record<string, string[]>;\n}\n\nexport type ToFrame =\n  | { type: 'init'; config: unknown; state: unknown; globals: Globals }\n  | { type: 'config'; config: unknown }\n  | { type: 'state'; state: unknown }\n  | { type: 'globals'; globals: Globals }\n  | { type: 'vars.set'; name: string; value: string | null }\n  | { type: 'play' };\n\nexport type FromFrame =\n  | { type: 'ready'; schema: SchemaDescription; layout: Layout; viewport: Viewport | null }\n  | { type: 'answers'; answers: ConfigAnswers }\n  | { type: 'setConfig'; path: string; value: unknown }\n  | { type: 'setState'; state: unknown }\n  | { type: 'size'; width: number; height: number }\n  | { type: 'vars'; vars: CssVarReport[] }\n  | { type: 'played'; ok: boolean; message?: string }\n  /** `seq`, on a render fault only: how many `init`/`config`/`state`/`globals` messages the frame had received. */\n  | { type: 'fault'; phase: FaultPhase; message: string; stack?: string; seq?: number };\n\nexport interface Envelope<M> {\n  v: number;\n  msg: M;\n}\n\n/** Posted on the frame's window with the port transferred alongside it. */\nexport const PORT_HANDOFF = 'weaselforge:port';\n\n/** JSON with object keys sorted, so two equal configs produce one key. */\nexport function stableStringify(value: unknown): string {\n  return JSON.stringify(value, (_key, v) =>\n    v && typeof v === 'object' && !Array.isArray(v)\n      ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : 1)))\n      : v,\n  );\n}\n"]}