@forgebook/story-format 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ensiria
+
+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

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @forgebook/story-format
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The story format of [Forgebook](https://www.npmjs.com/package/forgebook), as types: Component Story Format 3, generic
+over a framework, and the `StorySource` a package hands a catalogue. It has no dependencies, so a component library's
+stories depend on it and never on the catalogue that shows them.
+
+**Requirements:** none: no dependencies, types and a few small helpers ·
+[MIT licence](https://github.com/Ensiria/forgebook/blob/develop/packages/story-format/LICENSE)
+
+Most projects never install it themselves: `@forgebook/react` brings it, and its `Meta` and `Story` are this format
+typed for React. A library installs it to publish its stories for other catalogues:
+
+```ts
+// stories.ts, exported by the library as "@acme/ui/stories"
+/// <reference types="@forgebook/story-format/client" />
+import type { StorySource } from "@forgebook/story-format/source";
+
+import files from "./src/*.stories.tsx?forgebook-files";
+
+export const source: StorySource = {
+  id: "acme-ui",
+  name: "Acme UI",
+  files: [files],
+  sheets: { required: [], theme: [], restyled: [] }
+};
+```
+
+An app's `forgebook.config.ts` then lists it: `sources: ["@acme/ui/stories"]`.
+
+| Import | What it is |
+|---|---|
+| `@forgebook/story-format/csf` | The CSF 3 types, generic over a framework |
+| `@forgebook/story-format/source` | `StorySource`: a package's story files, style sheets, texts and home page |
+| `@forgebook/story-format/client` | The types of the `?forgebook-files` and `?forgebook-markdown` imports |
+| `@forgebook/story-format/texts` | Texts inside the stories, by key, in the catalogue's language |
+| `@forgebook/story-format/clock` | The story clock a live story reads |
+| `@forgebook/story-format/testing-library` | `canvas` and `userEvent` in every `play`, once Testing Library is installed |
+
+More: [Forgebook's README](https://github.com/Ensiria/forgebook/blob/develop/packages/forgebook/README.md).

package/dist/src/client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The types of the `?forgebook-files` and `?forgebook-markdown` imports, for the module that declares a source: add
+ * `@forgebook/story-format/client` to that folder's `compilerOptions.types`, beside `vite/client`.
+ *
+ * @remarks
+ * A script, not a module (no top-level import or export), so the wildcard declaration is global; the catalogue's Vite
+ * plugin answers each import with one module (D-438).
+ *
+ * @module
+ */
+
+declare module "*?forgebook-files" {
+  /** The story files the pattern before `?forgebook-files` matches. */
+  const files: import("./source").StoryFiles;
+  // the source imports the files as a default (`import files from "…?forgebook-files"`), so the module has one
+  // biome-ignore lint/style/noDefaultExport: see above
+  export default files;
+}
+
+declare module "*?forgebook-markdown" {
+  /** The Markdown file before `?forgebook-markdown`, as HTML (the source's introduction on the catalogue's home). */
+  const markdown: import("./source").StoryMarkdown;
+  // the source imports it as a default (`() => import("./home.md?forgebook-markdown")`), so the module has one
+  // biome-ignore lint/style/noDefaultExport: see above
+  export default markdown;
+}

package/dist/src/clock.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The story clock: the time a Live story reads, which the catalogue starts at a fixed moment and then runs, holds,
+ * restarts and speeds up (D-504).
+ *
+ * @remarks
+ * A component that counts (a countdown, a stream, a toast's wait) never reads the time itself: it takes a clock from
+ * its owner. In a story, that owner is the story, and the story's time comes from here: `context.clock` in a render
+ * or a play function; a framework's package gives components their own access (`useStoryClock()`, `useStoryNow()` in
+ * `@forgebook/react/clock`). The catalogue
+ * provides the clock; the library shown converts its milliseconds into its own time type, so this package names no
+ * date library and the catalogue none of the libraries it shows (D-67).
+ *
+ * The clock is stepped: `now()` is the moment of its last tick, the same value until the next one, so a render reads
+ * one moment throughout and a component can subscribe to it. A story that reads the clock declares
+ * `parameters.clock` with its start; the visual and generated tests hold the clock at that start, and a play
+ * function moves it with `advance` ("30 s later it says Expired"), never with a real wait. Without a catalogue (a
+ * story rendered on its own) the clock is held at the Unix epoch.
+ *
+ * @module
+ */
+/** The time a story reads. */
+export type StoryClock = {
+    /**
+     * The story's current moment, in whole milliseconds since the Unix epoch (what a date library takes as is): the
+     * moment of the clock's last tick.
+     */
+    readonly now: () => number;
+    /**
+     * Calls `onTick` at each tick and on every jump (advanced, restarted); returns what stops it.
+     *
+     * @param onTick - called once the clock moved.
+     */
+    readonly subscribe: (onTick: () => void) => () => void;
+    /**
+     * Moves the clock forward at once, whether it runs or is held: what a play function does instead of waiting.
+     *
+     * @param ms - how far, in milliseconds; a negative or non-finite value moves nothing.
+     */
+    readonly advance: (ms: number) => void;
+};
+/** A story's clock setting (`parameters.clock`): the story reads the clock, from this moment. */
+export type StoryClockSetting = {
+    /**
+     * The moment the clock starts at, and comes back to on Restart: an ISO 8601 instant with its offset
+     * (`2026-03-02T10:00:00Z`), so the story draws the same at its start every time.
+     */
+    readonly start: string;
+};
+/**
+ * A clock held at a moment: it moves only when advanced.
+ *
+ * @param start - its moment, in milliseconds since the Unix epoch.
+ * @returns the clock.
+ */
+export declare const heldStoryClock: (start: number) => StoryClock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/src/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8BAA8B;AAC9B,MAAM,MAAM,UAAU,GAAG;IACvB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC,CAAC;AAEF,iGAAiG;AACjG,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAAW,MAAM,KAAG,UAiB9C,CAAC"}

package/dist/src/clock.js

@@ -0,0 +1,27 @@
+/**
+ * A clock held at a moment: it moves only when advanced.
+ *
+ * @param start - its moment, in milliseconds since the Unix epoch.
+ * @returns the clock.
+ */
+export const heldStoryClock = (start) => {
+    let current = start;
+    const listeners = new Set();
+    return {
+        now: () => Math.floor(current),
+        subscribe: (onTick) => {
+            listeners.add(onTick);
+            return () => {
+                listeners.delete(onTick);
+            };
+        },
+        advance: (ms) => {
+            if (!Number.isFinite(ms) || ms <= 0)
+                return;
+            current += ms;
+            for (const listener of listeners)
+                listener();
+        }
+    };
+};
+//# sourceMappingURL=clock.js.map

package/dist/src/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/clock.ts"],"names":[],"mappings":"AAkDA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAa,EAAc,EAAE;IAC1D,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IACxC,OAAO;QACL,GAAG,EAAE,GAAW,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;QACtC,SAAS,EAAE,CAAC,MAAkB,EAAgB,EAAE;YAC9C,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACtB,OAAO,GAAS,EAAE;gBAChB,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3B,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,CAAC,EAAU,EAAQ,EAAE;YAC5B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;gBAAE,OAAO;YAC5C,OAAO,IAAI,EAAE,CAAC;YACd,KAAK,MAAM,QAAQ,IAAI,SAAS;gBAAE,QAAQ,EAAE,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/src/csf.d.ts

@@ -0,0 +1,332 @@
+/**
+ * The story format: Component Story Format 3, the subset the Ensiria catalogue reads.
+ *
+ * @remarks
+ * A story file exports its meta as the default export and each story as a named export, as CSF requires, so
+ * Storybook or Ladle could read the same files (D-54). The types cover only what the catalogue reads; anything else
+ * in a story file is left alone. The format is its own package so the packages that write stories depend on it, not
+ * on the catalogue that shows them. Parameters the catalogue adds (`forceState`, `replay`) sit under `parameters`, where CSF
+ * keeps tool-specific settings.
+ * A Live story (`parameters.clock`) reads the story clock the catalogue runs (`./clock`, D-504).
+ *
+ * The types are generic over a renderer, as Storybook's are: what a framework's component is and what a render
+ * returns. A framework's package names them for its own (`Meta<typeof Button>` in `@forgebook/react`), and story
+ * files import them from there; nothing here depends on a framework.
+ *
+ * @module
+ */
+import type { StoryClock, StoryClockSetting } from "./clock.ts";
+import type { StoryTextArg, StoryTextFunction } from "./texts.ts";
+/**
+ * A framework, as the story types read it: what a meta names as its component, and what a render, a decorator and a
+ * language's provider return.
+ */
+export type Renderer = {
+    /** A component of the framework. */
+    readonly component: unknown;
+    /** What a story draws (`ReactNode` in React). */
+    readonly storyResult: unknown;
+};
+/** A value a story's args may write for a prop: the prop's own, or, where it takes a text, a text named by its key. */
+export type WrittenArg<TValue> = string extends TValue ? TValue | StoryTextArg : TValue;
+/** An interaction state the catalogue can show without the pointer or the keyboard (`parameters.forceState`). */
+export type ForcedState = "hover" | "active" | "focus" | "focus-visible" | "focus-within";
+/**
+ * How the Replay control replays a story: `remount` mounts it again (an entrance), `{ toggle }` sets that boolean arg
+ * to false and, once the exit has played, back to true (an exit and an entrance).
+ */
+export type ReplayMode = "remount" | {
+    /** The boolean arg turned false then true again. */
+    readonly toggle: string;
+    /** How long the arg stays false once the exit has played, in ms (a loading phase to watch); none by default. */
+    readonly hold?: number;
+};
+/**
+ * A group of stories in the sidebar (`states`, `in-context`): its order and heading come from the catalogue's
+ * configuration (or a library's preset); a group it does not name sits after the named ones.
+ */
+export type StoryGroup = string;
+/** The controls an arg can have in the props panel, as Storybook names them. */
+export type ArgControlType = "select" | "radio" | "inline-radio" | "check" | "inline-check" | "multi-select" | "boolean" | "text" | "number" | "range" | "color" | "date" | "object" | "file";
+/** An arg's control: its type, or `false` for none, or the type with its settings. */
+export type ArgControl = ArgControlType | false | {
+    /** The control; from the arg's type when left out. */
+    readonly type?: ArgControlType;
+    /** The names the panel shows for the options, by option. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** A range's or a number's lowest value. */
+    readonly min?: number;
+    /** A range's or a number's highest value. */
+    readonly max?: number;
+    /** A range's or a number's step. */
+    readonly step?: number;
+    /** Whether the control is off: the arg is shown, not set. */
+    readonly disable?: boolean;
+};
+/**
+ * How the props panel shows one arg (Storybook's `argTypes`): over what the component's types say, or alone for an
+ * arg the types do not name. The story's entry is laid over the meta's.
+ */
+export type ArgType = {
+    /** The name the panel shows; the arg's by default. */
+    readonly name?: string;
+    /** What the arg does, over its TSDoc. */
+    readonly description?: string;
+    /** Its control. */
+    readonly control?: ArgControl;
+    /** The values a choice offers: texts or numbers, or keys of `mapping`. */
+    readonly options?: readonly unknown[];
+    /** The value each option stands for, by option: the panel sends the option, the story receives the value. */
+    readonly mapping?: Readonly<Record<string, unknown>>;
+    /** The table's settings: `disable` hides the arg from the panel. */
+    readonly table?: {
+        readonly disable?: boolean;
+    };
+    /** Records the arg's calls in the Events tab, under this name (Storybook's actions); a spy (`fn()`) is recorded too. */
+    readonly action?: string;
+};
+/** A story's or a meta's `argTypes`, by arg. */
+export type ArgTypes<TArgs> = {
+    readonly [Name in keyof TArgs]?: ArgType;
+} & Readonly<Record<string, ArgType>>;
+/** The settings the catalogue reads from a meta or a story; anything else under `parameters` is left alone. */
+export type StoryParameters = {
+    /** The states forced on the whole story; a part can force its own with `data-forgebook-force`. */
+    readonly forceState?: ForcedState | readonly ForcedState[];
+    /** Shows the Replay control and says what it does. */
+    readonly replay?: ReplayMode;
+    /**
+     * The props the panel can set for the story: every adjustable prop by default, only the listed ones, or none
+     * (`false`) for a story that draws fixed examples and ignores its args, which then shows no props (its column stays, empty, so the story keeps its width). With a list, the
+     * others are listed without a control. Storybook's `{ include, exclude }` is read too: `include` as the list,
+     * `exclude` hiding those args.
+     */
+    readonly controls?: false | readonly string[] | {
+        readonly include?: readonly string[];
+        readonly exclude?: readonly string[];
+    };
+    /** The story's group in the sidebar, a plain string (the index reads it); none puts it above the groups. */
+    readonly group?: StoryGroup;
+    /**
+     * Whether the story is the component's demo, drawn at the top of its page: one real, well-made use of it, not a
+     * matrix of its values. Written plainly (`main: true`, the index reads it); without one, the page shows `Overview`.
+     */
+    readonly main?: boolean;
+    /**
+     * The height the story's scene needs, in CSS px: the frame has it from the start, so an overlay the story opens is
+     * placed once, as in a window of that size, instead of flipping or scrolling in a frame only as tall as the story's
+     * own content. The frame still grows past it with its content (D-469). Written plainly (`height: 320`, the index
+     * reads it).
+     */
+    readonly height?: number;
+    /**
+     * The story reads the story clock (`context.clock`, `useStoryNow`): a Live story, which starts at this moment and
+     * then runs; the catalogue shows pause, resume, restart and the speed, and the tests hold it at its start (D-504).
+     * None by default: the clock is held at the Unix epoch and the catalogue shows no clock controls.
+     */
+    readonly clock?: StoryClockSetting;
+    /** How the story sits in its frame: padded (default), centred, or the whole frame. */
+    readonly layout?: "padded" | "centered" | "fullscreen";
+    /** CSF's documentation block; the catalogue reads the component's one-line description from it. */
+    readonly docs?: {
+        readonly description?: {
+            readonly component?: string;
+        };
+    };
+};
+/**
+ * Names a part of a play function: the catalogue's Interactions tab lists each step with its status and time, so a
+ * failing play shows where it stopped. Outside a play, it only runs the part.
+ */
+export type StepFunction = (label: string, run: () => Promise<void> | void) => Promise<void>;
+/** What a story's render, play and decorators receive. */
+export type StoryContext<TArgs> = {
+    /** The args: the meta's, the story's and the props panel's, merged in that order. */
+    readonly args: TArgs;
+    /** The element the story renders into. */
+    readonly canvasElement: HTMLElement;
+    /** Names a part of the play function (CSF's `step`). */
+    readonly step: StepFunction;
+    /** The text of a key in the shown language (`stories/locales/<id>.json`), its `{name}` placeholders filled. */
+    readonly text: StoryTextFunction;
+    /**
+     * The story clock: the time a Live story reads, and what its play function advances instead of waiting; held at
+     * the Unix epoch when the story declares no `parameters.clock` (D-504).
+     */
+    readonly clock: StoryClock;
+    /**
+     * The values of the catalogue's switches applied by code, by the switch's id (CSF's name): what a decorator reads
+     * to pick a provider's theme, a density, a locale. Empty outside a catalogue.
+     */
+    readonly globals: Readonly<Record<string, string>>;
+    /** What the story's loaders returned, merged: the preview's, then the meta's, then the story's (CSF's `loaded`). */
+    readonly loaded: Readonly<Record<string, unknown>>;
+    /** The story's id in the catalogue (`kit:inputs-select--overview`). */
+    readonly id: string;
+    /** The story's name as the catalogue shows it (`Keyboard open`). */
+    readonly name: string;
+    /** The title of its file's meta (`Inputs/Select`). */
+    readonly title: string;
+    /** The story's parameters: the preview's, under the meta's, under its own. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+};
+/**
+ * What a play function receives besides the story's context, filled in by the libraries the project installs.
+ *
+ * @remarks
+ * Empty here: Forgebook depends on no testing library. A project that installs `@testing-library/dom` and
+ * `@testing-library/user-event` gets `canvas` and `userEvent` in every play, and imports
+ * `@forgebook/story-format/testing-library` once to type them (it adds them to this interface).
+ */
+export interface StoryPlayTools {
+}
+/** What a play function receives: the story's context, its `step`, and the play tools the project installed. */
+export type StoryPlayContext<TArgs> = StoryContext<TArgs> & StoryPlayTools;
+/**
+ * What a loader and a `beforeEach` receive: the story's args and what it is shown with, before it is drawn. No canvas:
+ * they also run before a story is drawn on the server, where there is none.
+ */
+export type StoryHookContext<TArgs> = Pick<StoryContext<TArgs>, "args" | "text" | "clock" | "globals" | "loaded" | "id" | "name" | "title" | "parameters">;
+/**
+ * Fetches what a story needs before it is drawn (CSF's loader): what it returns reaches the story's render, play and
+ * decorators as `context.loaded`. Every loader of a story runs at once; a later one's key wins (the story's over the
+ * meta's over the preview's). It receives an empty `loaded`.
+ */
+export type StoryLoader<TArgs> = (context: StoryHookContext<TArgs>) => Promise<Readonly<Record<string, unknown>> | undefined> | Readonly<Record<string, unknown>> | undefined;
+/** Undoes what a `beforeEach` set up: run when the story is mounted again or its frame is left. */
+export type StoryCleanup = () => Promise<void> | void;
+/**
+ * Sets up what a story needs before it is drawn, after its loaders (CSF's `beforeEach`: a mocked date, a stored
+ * value), one after another: the preview's, the meta's, the story's. It may return the cleanup that undoes it.
+ */
+export type StoryBeforeEach<TArgs> = (context: StoryHookContext<TArgs>) => Promise<StoryCleanup | undefined> | StoryCleanup | undefined;
+/** One function of a kind, or a list of them, as CSF lets a meta, a story or a preview write it. */
+export type OneOrMany<TFunction> = TFunction | readonly TFunction[];
+/** Wraps a story: a provider, a container of a given width. */
+export type Decorator<TRenderer extends Renderer, TArgs> = (story: () => TRenderer["storyResult"], context: StoryContext<TArgs>) => TRenderer["storyResult"];
+/**
+ * A story file's default export, for a framework: `TComponent` is the component it shows, `TArgs` what its render
+ * receives and `TWrittenArgs` what its args may write (a framework's package derives both from the component's props).
+ */
+export type CsfMeta<TRenderer extends Renderer, TComponent, TArgs, TWrittenArgs> = {
+    /**
+     * Where it sits in the catalogue: `Family/Name` or `Family/Group/Name` (`Inputs/Selection/Select`); any depth is
+     * placed. Written plainly; without one, the file's path from its pattern's folder is the title.
+     */
+    readonly title?: string;
+    /** The component the stories show; their args are its props. */
+    readonly component?: TComponent;
+    /**
+     * The parts the component is used with that have no story file of their own (`{ ChipList }` beside `Chip`), by the
+     * name the catalogue shows: the component's page lists each one's props under its own. Storybook's
+     * `subcomponents`, so the stories stay readable by it. Written in the meta as an object of imported components: the
+     * catalogue reads it without running the file.
+     */
+    readonly subcomponents?: Readonly<Record<string, TRenderer["component"]>>;
+    /** Args every story of the file starts from. */
+    readonly args?: TWrittenArgs;
+    /** How the props panel shows the args (Storybook's `argTypes`). */
+    readonly argTypes?: ArgTypes<TWrittenArgs>;
+    /**
+     * The catalogue's switches the story fixes, by the switch's id (`{ theme: "dark" }`), and Storybook's
+     * `backgrounds` and `viewport` (`{ backgrounds: { value: "dark" } }`): drawn so whatever the toolbar says, which
+     * shows them as set by the story.
+     */
+    readonly globals?: Readonly<Record<string, unknown>>;
+    /**
+     * Other places the catalogue lists the component in, besides its title's, as `Family` or `Family/Group`
+     * (`["Data/Tables"]`): a component that belongs to one family but is looked for in another. Each place shows an
+     * entry marked as living elsewhere that opens the same page, so nothing is duplicated: no second story, test or
+     * image (D-492). Written plainly, a list of string literals: the catalogue reads it without running the file.
+     */
+    readonly alsoIn?: readonly string[];
+    /**
+     * The titles of related components of the same source (`["Layout/Inline"]`): each page names the other at its top,
+     * both ways, so writing the link in one meta is enough (D-492). Written plainly, a list of string literals.
+     */
+    readonly related?: readonly string[];
+    /**
+     * Other words the catalogue's search finds the component by, besides its name and title: the names other libraries
+     * give it (`["horizontal", "row", "hstack"]` for `Inline`). Written plainly, a list of string literals (D-603).
+     */
+    readonly keywords?: readonly string[];
+    /** Settings for every story of the file. */
+    readonly parameters?: StoryParameters;
+    /** Wrappers for every story of the file, outermost last. */
+    readonly decorators?: readonly Decorator<TRenderer, TArgs>[];
+    /** What every story of the file renders when it writes no render of its own. */
+    readonly render?: (args: TArgs, context: StoryContext<TArgs>) => TRenderer["storyResult"];
+    /** The play function of every story of the file that writes none of its own. */
+    readonly play?: (context: StoryPlayContext<TArgs>) => Promise<void> | void;
+    /** Loaders for every story of the file, after the preview's. */
+    readonly loaders?: OneOrMany<StoryLoader<TArgs>>;
+    /** Set-ups for every story of the file, after the preview's. */
+    readonly beforeEach?: OneOrMany<StoryBeforeEach<TArgs>>;
+    /** Tags of every story of the file (`["autodocs"]`); a story's `!name` takes one away. Written plainly. */
+    readonly tags?: readonly string[];
+    /** The named exports that are stories: a list of names or a regular expression; every one by default. */
+    readonly includeStories?: readonly string[] | RegExp;
+    /** The named exports that are not stories (shared data): a list of names or a regular expression. */
+    readonly excludeStories?: readonly string[] | RegExp;
+};
+/** A story, a named export of a story file, for a framework: its args as in `CsfMeta`. */
+export type CsfStory<TRenderer extends Renderer, TArgs, TWrittenArgs> = {
+    /** The name in the catalogue; by default the export's name in sentence case (`KeyboardOpen` → "Keyboard open"). */
+    readonly name?: string;
+    /** Args over the meta's. */
+    readonly args?: TWrittenArgs;
+    /** How the props panel shows the args (Storybook's `argTypes`). */
+    readonly argTypes?: ArgTypes<TWrittenArgs>;
+    /**
+     * The catalogue's switches the story fixes, by the switch's id (`{ theme: "dark" }`), and Storybook's
+     * `backgrounds` and `viewport` (`{ backgrounds: { value: "dark" } }`): drawn so whatever the toolbar says, which
+     * shows them as set by the story.
+     */
+    readonly globals?: Readonly<Record<string, unknown>>;
+    /** What the story renders; by default the meta's component with the args. */
+    readonly render?: (args: TArgs, context: StoryContext<TArgs>) => TRenderer["storyResult"];
+    /** Runs after the story renders: a keyboard flow, an async path (the tests run it too). */
+    readonly play?: (context: StoryPlayContext<TArgs>) => Promise<void> | void;
+    /** Settings over the meta's. */
+    readonly parameters?: StoryParameters;
+    /** Wrappers inside the meta's. */
+    readonly decorators?: readonly Decorator<TRenderer, TArgs>[];
+    /** Loaders after the meta's. */
+    readonly loaders?: OneOrMany<StoryLoader<TArgs>>;
+    /** Set-ups after the meta's. */
+    readonly beforeEach?: OneOrMany<StoryBeforeEach<TArgs>>;
+    /** Tags over the meta's: `!name` takes one of the meta's away. Written plainly. */
+    readonly tags?: readonly string[];
+};
+/**
+ * A catalogue's preview (`forgebook.preview.ts`), for a framework: what applies to every story in the frames. Its
+ * decorators wrap every story outside the meta's and the story's own (a provider, the language's provider reading
+ * `context.globals.lang`), its parameters sit under every meta's, its setup runs once before any story renders, and
+ * its loaders and set-ups run before every story's own.
+ */
+export type CsfPreview<TRenderer extends Renderer> = {
+    /** Wrappers for every story, outermost last. */
+    readonly decorators?: readonly Decorator<TRenderer, Readonly<Record<string, unknown>>>[];
+    /** Settings every story starts from, under its meta's and its own. */
+    readonly parameters?: StoryParameters;
+    /** What the stories need before any renders (a polyfill to load); nothing by default. */
+    readonly setup?: () => Promise<void>;
+    /** Loaders for every story, before the meta's and the story's. */
+    readonly loaders?: OneOrMany<StoryLoader<Readonly<Record<string, unknown>>>>;
+    /** Set-ups for every story, before the meta's and the story's. */
+    readonly beforeEach?: OneOrMany<StoryBeforeEach<Readonly<Record<string, unknown>>>>;
+    /** Args every story starts from, under its meta's (Storybook's project args). */
+    readonly args?: Readonly<Record<string, unknown>>;
+    /** How the props panel shows args of every story, under the meta's and the story's. */
+    readonly argTypes?: Readonly<Record<string, ArgType>>;
+    /**
+     * Storybook's toolbar of the preview's own globals: read by the configuration on Node, through
+     * `switchesFromGlobalTypes`, never by the frames.
+     */
+    readonly globalTypes?: Readonly<Record<string, unknown>>;
+    /** The globals' first values, for `switchesFromGlobalTypes`. */
+    readonly initialGlobals?: Readonly<Record<string, unknown>>;
+    /** Tags of every story, under the meta's. */
+    readonly tags?: readonly string[];
+};
+//# sourceMappingURL=csf.d.ts.map

package/dist/src/csf.d.ts.map

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

package/dist/src/csf.js

@@ -0,0 +1,21 @@
+/**
+ * The story format: Component Story Format 3, the subset the Ensiria catalogue reads.
+ *
+ * @remarks
+ * A story file exports its meta as the default export and each story as a named export, as CSF requires, so
+ * Storybook or Ladle could read the same files (D-54). The types cover only what the catalogue reads; anything else
+ * in a story file is left alone. The format is its own package so the packages that write stories depend on it, not
+ * on the catalogue that shows them. Parameters the catalogue adds (`forceState`, `replay`) sit under `parameters`, where CSF
+ * keeps tool-specific settings.
+ * A Live story (`parameters.clock`) reads the story clock the catalogue runs (`./clock`, D-504).
+ *
+ * The types are generic over a renderer, as Storybook's are: what a framework's component is and what a render
+ * returns. A framework's package names them for its own (`Meta<typeof Button>` in `@forgebook/react`), and story
+ * files import them from there; nothing here depends on a framework.
+ *
+ * @module
+ */
+// a story draws in a page (`canvasElement`): code on Node that reads these types (the catalogue's plugin) gets the DOM's
+// types from here
+/// <reference lib="dom" />
+//# sourceMappingURL=csf.js.map

package/dist/src/csf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csf.js","sourceRoot":"","sources":["../../src/csf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,yHAAyH;AACzH,kBAAkB;AAClB,2BAA2B"}

package/dist/src/source.d.ts

@@ -0,0 +1,184 @@
+/**
+ * What a package hands a catalogue: its story files, its style sheets, its texts.
+ *
+ * @remarks
+ * Every package with stories exports one `StorySource` from a development-only `./stories` subpath, never published;
+ * an app lists the sources it shows (D-57). A source names its story files once per pattern, with an import the
+ * catalogue's Vite plugin answers (`import files from "../src/**\/*.stories.tsx?forgebook-files"`, typed by
+ * `@forgebook/story-format/client`): one module with every file's index (read without running the files), and the loaders
+ * of its stories, its component's docs and its code (D-438). The style sheets are the URLs the frame loads for each
+ * Styles setting.
+ *
+ * @module
+ */
+import type { StoryGroup } from "./csf.ts";
+/** The props the panel can set for a story: every adjustable one, or only the named ones (none for fixed examples). */
+export type StoryControlsSetting = "all" | readonly string[];
+/** One story of a file, as the index lists it. */
+export type StoryIndexEntry = {
+    /** The named export (`KeyboardOpen`). */
+    readonly exportName: string;
+    /** The name written in the story, when it has one (`name: "Keyboard · open"`). */
+    readonly name?: string;
+    /** The story's own `parameters.controls`, when it sets one: `[]` for `false`. */
+    readonly controls?: StoryControlsSetting;
+    /** The story's `parameters.group`, when it sets one. */
+    readonly group?: StoryGroup;
+    /** The story's own `parameters.height`, when it sets one, in CSS px (D-469). */
+    readonly height?: number;
+    /** Whether the story sets `parameters.main: true`: the component's demo. */
+    readonly isMain?: boolean;
+    /**
+     * The first sentence of the story's TSDoc, or its `parameters.docs.description.story`: what it shows and what to
+     * notice.
+     */
+    readonly description?: string;
+    /** The story's tags, the meta's then its own, a `!name` taking `name` away (Storybook's tags). */
+    readonly tags?: readonly string[];
+};
+/** One story file, read statically: what the catalogue shows before loading it. */
+export type StoryFileIndex = {
+    /** The meta's title (`Inputs/Selection/Select`). */
+    readonly title: string;
+    /** The meta's `parameters.controls`, when it sets one: `[]` for `false`. */
+    readonly controls?: StoryControlsSetting;
+    /** The meta's `parameters.height`, when it sets one: every story's frame height, in CSS px (D-469). */
+    readonly height?: number;
+    /** The meta's `alsoIn`, when it sets one: the other places the component is listed in (D-492). */
+    readonly alsoIn?: readonly string[];
+    /** The meta's `related`, when it sets one: the titles of the components its page names at its top (D-492). */
+    readonly related?: readonly string[];
+    /** The meta's `keywords`, when it sets one: other words the search finds the component by (D-603). */
+    readonly keywords?: readonly string[];
+    /** The meta's `parameters.docs.description.component`, when written plainly. */
+    readonly description?: string;
+    /** What the index noticed without refusing the file (a title written by code, placed by its path). */
+    readonly notes?: readonly string[];
+    /** Its stories, in the order of the file (or of its `__namedExportsOrder`). */
+    readonly stories: readonly StoryIndexEntry[];
+};
+/** The style sheets of a package, as URLs, for each Styles setting of the toolbar. */
+export type StorySheets = {
+    /** Always loaded: the tokens and the structure. */
+    readonly required: readonly string[];
+    /** Loaded with Styles › Full: the theme. */
+    readonly theme: readonly string[];
+    /** Loaded with Styles › Restyled, instead of the theme: a consumer's own look through the public hooks. */
+    readonly restyled: readonly string[];
+};
+/**
+ * A language a catalogue offers (the View menu's Language row): its id and name, and whether its texts are a
+ * pseudo-translation. Data only: the provider that draws a story in a language is a decorator of the catalogue's
+ * preview, which reads the language as `context.globals.lang`.
+ */
+export type StoryLanguage = {
+    /** A stable id, written in the address (`pseudo`). */
+    readonly id: string;
+    /** The name in the View menu (`Pseudo`). */
+    readonly label: string;
+    /**
+     * Whether the stories' own texts are drawn as a pseudo-translation of the English ones (accented, longer, in
+     * brackets) instead of a table of their own; `false` by default.
+     */
+    readonly isPseudo?: boolean;
+};
+/** A story's `render` as written in its file. */
+export type StoryCode = {
+    /** The text, as copied. */
+    readonly text: string;
+    /** The same text as HTML, coloured by the catalogue's plugin at build time. */
+    readonly html: string;
+};
+/** Each story's `render` as written in its file, by export name; a story without one is left out. */
+export type StoryFileCode = Readonly<Record<string, StoryCode>>;
+/**
+ * A group of story files, as the catalogue's plugin answers a `?forgebook-files` import: each file's index, and the
+ * loaders of its module, of its component's docs and of its code, all by the file's path relative to the importing
+ * module (`../src/inputs/select/Select.stories.tsx`).
+ */
+export type StoryFiles = {
+    /** Each file's index: its title and stories, read without running it. */
+    readonly index: Readonly<Record<string, StoryFileIndex>>;
+    /** Each file's module, loaded when a frame shows one of its stories. */
+    readonly stories: Readonly<Record<string, () => Promise<unknown>>>;
+    /** Each file's component docs, for the props panel (`{ error }` when they cannot be read, `{ name: null }` for none). */
+    readonly docs: Readonly<Record<string, () => Promise<unknown>>>;
+    /** Each file's code: each story's `render` as written, for the Code tab. */
+    readonly code: Readonly<Record<string, () => Promise<unknown>>>;
+    /** Each file's component page: its Markdown documentation, beside the story file, as HTML (`{ none: true }` without). */
+    readonly pages: Readonly<Record<string, () => Promise<unknown>>>;
+};
+/**
+ * The colour of the page a source's stories open on, by theme and contrast: the catalogue paints a story's box with it
+ * while the story loads, so the box is not white before a dark story and does not change colour when the story shows.
+ * A CSS colour each; the more-contrast ones fall back to their scheme's.
+ */
+export type StoryBackground = {
+    /** The light theme's. */
+    readonly light: string;
+    /** The dark theme's. */
+    readonly dark: string;
+    /** The light theme's with more contrast; `light` when left out. */
+    readonly lightMore?: string;
+    /** The dark theme's with more contrast; `dark` when left out. */
+    readonly darkMore?: string;
+};
+/** A Markdown file as the catalogue's plugin answers a `?forgebook-markdown` import: its text as HTML. */
+export type StoryMarkdown = {
+    /** The file as HTML, its first `#` title left out (the catalogue shows the source's name). */
+    readonly html: string;
+};
+/** A package's stories, as the catalogue reads them. */
+export type StorySource = {
+    /** A stable id, part of every story id's URL (`acme-ui`). */
+    readonly id: string;
+    /** The name in the sidebar (`Acme UI`). */
+    readonly name: string;
+    /**
+     * The package's logo, shown beside its name in the sidebar and on the home: the URL of a square image, drawn for a
+     * light surface (`import logoUrl from "./logo.svg?url"`). None by default.
+     */
+    readonly logo?: string;
+    /**
+     * The colour the stories' page has (the frame's `body`, as the source's frame style sheet sets it), by theme and
+     * contrast, for the box a story loads in. None by default: the box waits on the catalogue's own surface.
+     */
+    readonly background?: StoryBackground;
+    /** The families in the order the sidebar lists them; families not listed follow, alphabetically. */
+    readonly families?: readonly string[];
+    /**
+     * The groups of a family in the order the sidebar lists them, by family (`{ Inputs: ["Text", "Choice"] }`): a
+     * family's own components without a group come first, then its groups as listed, then the groups not listed,
+     * alphabetically. None by default: every family's groups alphabetically.
+     */
+    readonly familyGroups?: Readonly<Record<string, readonly string[]>>;
+    /** Its story files: one group per `?forgebook-files` import, the keys unique across the groups. */
+    readonly files: readonly StoryFiles[];
+    /** The style sheets. */
+    readonly sheets: StorySheets;
+    /**
+     * Values the props panel offers by name for a type it cannot write (a component, a function), keyed by the type as
+     * TypeScript writes it in the props (`IconComponent`), then by the name shown and written in the JSX
+     * (`IconFolder`): `{ IconComponent: { IconFolder, IconBell } }`. None by default.
+     */
+    readonly namedValues?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    /**
+     * The texts inside the stories, by language id (the ids of the catalogue's languages; `en` the one every key is in):
+     * the package's `stories/locales/<id>.json`. A story reads them with `useStoryText()` or `context.text()`; none by
+     * default.
+     */
+    readonly texts?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /**
+     * What the source needs before any of its stories renders (a polyfill to load), awaited by the frame and by the
+     * server tests; nothing by default.
+     */
+    readonly setup?: () => Promise<void>;
+    /**
+     * The source's introduction on the catalogue's home, written by the package: what it is, how to start
+     * (`home: () => import("./home.md?forgebook-markdown")`). None by default: the home then shows only its families.
+     */
+    readonly home?: () => Promise<{
+        readonly default: StoryMarkdown;
+    }>;
+};
+//# sourceMappingURL=source.d.ts.map

package/dist/src/source.d.ts.map

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

package/dist/src/source.js

@@ -0,0 +1 @@
+//# sourceMappingURL=source.js.map

package/dist/src/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/source.ts"],"names":[],"mappings":""}

package/dist/src/testingLibrary.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The types of the play tools a project gets by installing Testing Library: imported once, as
+ * `import "@forgebook/story-format/testing-library"`, it adds `canvas` and `userEvent` to every play function's
+ * context.
+ *
+ * @remarks
+ * Forgebook depends on no testing library; when the project installs `@testing-library/dom` and
+ * `@testing-library/user-event`, the catalogue's frame hands every play `canvas` (Testing Library's queries bound to the
+ * story's canvas, as Storybook's) and `userEvent`. Without them, importing this module fails to type-check, as the
+ * frame would have nothing to hand.
+ *
+ * @module
+ */
+import type { BoundFunctions, queries } from "@testing-library/dom";
+import type { UserEvent } from "@testing-library/user-event";
+declare module "./csf.ts" {
+    /** The play tools Testing Library gives. */
+    interface StoryPlayTools {
+        /** Testing Library's queries, bound to the story's canvas (`canvas.getByRole("button")`). */
+        readonly canvas: BoundFunctions<typeof queries>;
+        /** Testing Library's user events (`await userEvent.click(button)`). */
+        readonly userEvent: UserEvent;
+    }
+}
+//# sourceMappingURL=testingLibrary.d.ts.map

package/dist/src/testingLibrary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingLibrary.d.ts","sourceRoot":"","sources":["../../src/testingLibrary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAE7D,OAAO,QAAQ,UAAU,CAAC;IACxB,4CAA4C;IAC5C,UAAU,cAAc;QACtB,6FAA6F;QAC7F,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,OAAO,OAAO,CAAC,CAAC;QAChD,uEAAuE;QACvE,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;KAC/B;CACF"}

package/dist/src/testingLibrary.js

@@ -0,0 +1 @@
+//# sourceMappingURL=testingLibrary.js.map

package/dist/src/testingLibrary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testingLibrary.js","sourceRoot":"","sources":["../../src/testingLibrary.ts"],"names":[],"mappings":""}

package/dist/src/texts.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The texts inside the stories (a card's title, a row's sample name), in the language the catalogue shows: a story
+ * names a text by its key, and the package's locale files hold the words (`stories/locales/en.json`, `it.json`, …).
+ *
+ * @remarks
+ * The catalogue provides the texts of the shown language, English where a language lacks a key; a story reads them
+ * with `context.text()` in a render or a play function, or a framework's own access in a component (`useStoryText()`
+ * in `@forgebook/react/texts`), and an
+ * arg names one with `storyText("key")`: args are plain data, written before any language is known, so the catalogue
+ * gives the story the text in the shown language and the props panel shows it with its key. A key is written as a
+ * plain string literal (`text("skeleton.dashboard.title")`, `storyText("button.save")`), so `forgebook-texts` can find
+ * every key the stories use. Values may hold `{name}` placeholders, filled from the second argument. Without a provider (a test
+ * rendering a story on its own) a text is its key in brackets, never an empty string.
+ *
+ * @module
+ */
+/** One language's texts, by key. */
+export type StoryTextTable = Readonly<Record<string, string>>;
+/** The values a text's `{name}` placeholders take. */
+export type StoryTextValues = Readonly<Record<string, string | number>>;
+/** Gives the text of a key in the shown language, its placeholders filled. */
+export type StoryTextFunction = (key: string, values?: StoryTextValues) => string;
+/**
+ * A text with its `{name}` placeholders filled; a placeholder without a value stays as it is.
+ *
+ * @param text - the text.
+ * @param values - the placeholders' values; none by default.
+ */
+export declare const filledText: (text: string, values?: StoryTextValues) => string;
+/**
+ * The text function over a table: a key the table lacks is the key in brackets, so a missing text shows.
+ *
+ * @param table - the texts of the shown language, English filled in.
+ */
+export declare const storyTextOf: (table: StoryTextTable) => StoryTextFunction;
+/** An arg that names a text: the story receives the text of the key in the shown language, its placeholders filled. */
+export type StoryTextArg = {
+    /** The text's key. */
+    readonly storyText: string;
+    /** The values of its `{name}` placeholders; none by default. */
+    readonly values?: StoryTextValues;
+};
+/**
+ * An arg that names a text, for a prop that takes one: `args: { children: storyText("button.save") }`.
+ *
+ * @param key - the text's key, a plain string literal.
+ * @param values - the values of its `{name}` placeholders; none by default.
+ */
+export declare const storyText: (key: string, values?: StoryTextValues) => StoryTextArg;
+/**
+ * Whether an arg names a text.
+ *
+ * @param value - a story's arg.
+ */
+export declare const isStoryTextArg: (value: unknown) => value is StoryTextArg;
+//# sourceMappingURL=texts.d.ts.map

package/dist/src/texts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texts.d.ts","sourceRoot":"","sources":["../../src/texts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,oCAAoC;AACpC,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9D,sDAAsD;AACtD,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;AAExE,8EAA8E;AAC9E,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,MAAM,CAAC;AAElF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,SAAU,MAAM,WAAU,eAAe,KAAQ,MAIpE,CAAC;AAEL;;;;GAIG;AACH,eAAO,MAAM,WAAW,UACd,cAAc,KAAG,iBAIxB,CAAC;AAEJ,uHAAuH;AACvH,MAAM,MAAM,YAAY,GAAG;IACzB,sBAAsB;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;CACnC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,QAAS,MAAM,WAAW,eAAe,KAAG,YACM,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAW,OAAO,KAAG,KAAK,IAAI,YACmD,CAAC"}

package/dist/src/texts.js

@@ -0,0 +1,33 @@
+/**
+ * A text with its `{name}` placeholders filled; a placeholder without a value stays as it is.
+ *
+ * @param text - the text.
+ * @param values - the placeholders' values; none by default.
+ */
+export const filledText = (text, values = {}) => text.replace(/\{(\w+)\}/g, (placeholder, name) => {
+    const value = values[name];
+    return value === undefined ? placeholder : String(value);
+});
+/**
+ * The text function over a table: a key the table lacks is the key in brackets, so a missing text shows.
+ *
+ * @param table - the texts of the shown language, English filled in.
+ */
+export const storyTextOf = (table) => (key, values) => {
+    const text = table[key];
+    return text === undefined ? `[${key}]` : filledText(text, values);
+};
+/**
+ * An arg that names a text, for a prop that takes one: `args: { children: storyText("button.save") }`.
+ *
+ * @param key - the text's key, a plain string literal.
+ * @param values - the values of its `{name}` placeholders; none by default.
+ */
+export const storyText = (key, values) => values === undefined ? { storyText: key } : { storyText: key, values };
+/**
+ * Whether an arg names a text.
+ *
+ * @param value - a story's arg.
+ */
+export const isStoryTextArg = (value) => typeof value === "object" && value !== null && "storyText" in value && typeof value.storyText === "string";
+//# sourceMappingURL=texts.js.map

package/dist/src/texts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"texts.js","sourceRoot":"","sources":["../../src/texts.ts"],"names":[],"mappings":"AAyBA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,MAAM,GAAoB,EAAE,EAAU,EAAE,CAC/E,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,WAAmB,EAAE,IAAY,EAAU,EAAE;IACvE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC,CAAC,CAAC;AAEL;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GACtB,CAAC,KAAqB,EAAqB,EAAE,CAC7C,CAAC,GAAW,EAAE,MAAwB,EAAU,EAAE;IAChD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC,CAAC;AAUJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAW,EAAE,MAAwB,EAAgB,EAAE,CAC/E,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AAEzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAc,EAAyB,EAAE,CACtE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,WAAW,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC"}

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@forgebook/story-format",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The story format of Forgebook: the CSF 3 types a story file is written with, generic over a framework, the StorySource a package hands a catalogue, the texts inside the stories in the shown language, and the story clock a Live story reads. No dependency: a library's stories depend on their framework's package, never on the catalogue that shows them.",
+  "keywords": [
+    "stories",
+    "csf",
+    "design-system"
+  ],
+  "license": "MIT",
+  "author": "Jason Scoppetta",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ensiria/forgebook.git",
+    "directory": "packages/story-format"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    "./csf": {
+      "types": "./dist/src/csf.d.ts",
+      "default": "./dist/src/csf.js"
+    },
+    "./clock": {
+      "types": "./dist/src/clock.d.ts",
+      "default": "./dist/src/clock.js"
+    },
+    "./source": {
+      "types": "./dist/src/source.d.ts",
+      "default": "./dist/src/source.js"
+    },
+    "./client": {
+      "types": "./dist/src/client.d.ts"
+    },
+    "./texts": {
+      "types": "./dist/src/texts.d.ts",
+      "default": "./dist/src/texts.js"
+    },
+    "./testing-library": {
+      "types": "./dist/src/testingLibrary.d.ts",
+      "default": "./dist/src/testingLibrary.js"
+    }
+  },
+  "devDependencies": {
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/user-event": "14.6.8",
+    "@forgebook/tools": "0.0.0",
+    "@forgebook/typescript-config": "0.0.0"
+  },
+  "peerDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/user-event": "^14.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@testing-library/dom": {
+      "optional": true
+    },
+    "@testing-library/user-event": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "package-build build",
+    "manifest": "package-build manifest",
+    "typecheck": "tsc -p src"
+  }
 }