@codepress/design-kit 0.1.0 → 0.1.2

package/src/kit.d.ts

@@ -0,0 +1,81 @@
+/** Types for `@codepress/design-kit/kit`, the kit tool's functions. */
+
+/** One row of `index.json` (stories) or `routes.json` (pages). */
+export interface KitRow {
+  id: string;
+  kind?: "story" | "route";
+  title?: string;
+  component?: string;
+  file: string;
+  width?: number;
+  height?: number;
+  bytes?: number;
+  slots?: string[];
+  source_file?: string;
+  body_class?: string;
+  html_attrs?: Record<string, string>;
+  body_attrs?: Record<string, string>;
+}
+
+export interface KitManifest {
+  kit_version?: number;
+  sha?: string;
+  built_at?: string;
+  [key: string]: unknown;
+}
+
+/** A loaded kit: its folder, manifest and rows, sorted and by id. */
+export interface Kit {
+  dir: string;
+  manifest: KitManifest | null;
+  rows: KitRow[];
+  byId: Map<string, KitRow>;
+}
+
+export function loadKit(dir: string): Kit;
+
+/** Rows whose id, title, component or source file holds every word. */
+export function find(kit: Kit, query: string): KitRow[];
+
+/** Up to five candidates, closest first. */
+export function nearMatches(wanted: string, candidates: string[]): string[];
+
+/** A markup outline of at most `limit` bytes. */
+export function outline(
+  html: string,
+  limit?: number,
+): { lines: string[]; truncated: boolean };
+
+/**
+ * One self-contained page. Throws an Error whose message starts with
+ * `unknown ` (and names near matches) for an unknown frame, slot or snippet,
+ * and with `too large: ` when snippets grow the page past `maxBytes`.
+ */
+export function compose(
+  kit: Kit,
+  options: {
+    frame: string;
+    slots?: { name: string; content: string }[];
+    theme?: "light" | "dark";
+    showNew?: boolean;
+    /** Bytes of markup the page may grow to through snippets. */
+    maxBytes?: number;
+  },
+): string;
+
+/** The default `maxBytes` of `compose`: 32 MB. */
+export const COMPOSE_MAX_BYTES: number;
+
+export function sanitizeMarkup(html: string): string;
+export function sanitizeCss(css: string): string;
+
+/** Runs one command line; returns the exit code. */
+export function run(
+  argv: string[],
+  io?: { out(text: string): void; err(text: string): void },
+  env?: Record<string, string | undefined>,
+  defaultDir?: string,
+): number;
+
+/** Whether this file is the script node was started with. */
+export function isMain(moduleUrl?: string, script?: string): boolean;

package/src/kit.mjs

@@ -19,6 +19,12 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const FIND_LIMIT = 30;
 const SHOW_LIMIT = 2048;
 const SNIPPET_DEPTH = 8;
+/**
+ * Bytes of markup one compose may read through <kit-snippet>s. Nesting is
+ * capped, but a file of many placeholders pointing at large rows would
+ * otherwise grow the page exponentially.
+ */
+export const COMPOSE_MAX_BYTES = 32 * 1024 * 1024;
 
 class KitError extends Error {}
 
@@ -672,7 +678,7 @@ export function inlineAssets(kit, css, cssDir = join(kit.dir, "css")) {
 
 // ── compose ─────────────────────────────────────────────────────────────────
 
-function expandSnippets(kit, html, used, depth = 0) {
+function expandSnippets(kit, html, used, budget, depth = 0) {
   const found = elements(html).filter((e) => e.name === "kit-snippet");
   if (!found.length) return html;
   if (depth >= SNIPPET_DEPTH) {
@@ -689,10 +695,16 @@ function expandSnippets(kit, html, used, depth = 0) {
     const row = requireRow(kit, id, "<kit-snippet id>");
     used.add(rowSource(row));
     let markup = readSnippet(kit, row);
+    budget.left -= markup.length;
+    if (budget.left < 0) {
+      throw new KitError(
+        `too large: the page grows past ${budget.max} bytes while expanding <kit-snippet> elements; use fewer or smaller snippets.`,
+      );
+    }
     if (rowSource(row) === "stories") markup = unwrapStoryRoot(markup);
     out +=
       html.slice(i, element.start) +
-      expandSnippets(kit, markup, used, depth + 1);
+      expandSnippets(kit, markup, used, budget, depth + 1);
     i = element.end;
   }
   return out + html.slice(i);
@@ -815,7 +827,13 @@ function attributes(captured, extraClass, theme, choice, target, fixed) {
  */
 export function compose(
   kit,
-  { frame, slots = [], theme = "light", showNew = false },
+  {
+    frame,
+    slots = [],
+    theme = "light",
+    showNew = false,
+    maxBytes = COMPOSE_MAX_BYTES,
+  },
 ) {
   const row = requireRow(kit, frame, "frame");
   if (theme !== "light" && theme !== "dark") {
@@ -823,7 +841,10 @@ export function compose(
   }
   const used = new Set([rowSource(row)]);
   const filled = fillSlots(kit, row, readSnippet(kit, row), slots);
-  const body = expandSnippets(kit, filled, used);
+  const body = expandSnippets(kit, filled, used, {
+    left: maxBytes - filled.length,
+    max: maxBytes,
+  });
 
   const css = ["stories", "routes"]
     .filter((source) => used.has(source))
@@ -1069,16 +1090,27 @@ export function run(
   }
 }
 
-/** Whether this file is the script node was started with (symlinks resolved). */
-function isMain() {
-  if (!process.argv[1]) return false;
+/**
+ * Whether this file is the script node was started with (symlinks resolved).
+ * Only a file named `kit.mjs` can be: a bundler that inlines this module into
+ * another program keeps `import.meta.url` pointing at that program, which is
+ * also the script node started, and the program would then run the kit's
+ * command line on its own arguments.
+ */
+export function isMain(moduleUrl = import.meta.url, script = process.argv[1]) {
+  if (!script) return false;
+  let self;
   try {
-    return (
-      realpathSync(fileURLToPath(import.meta.url)) ===
-      realpathSync(resolve(process.argv[1]))
-    );
+    self = fileURLToPath(moduleUrl);
+  } catch {
+    // Not a file URL: an evaluated bundle, never the script node started.
+    return false;
+  }
+  if (basename(self) !== "kit.mjs") return false;
+  try {
+    return realpathSync(self) === realpathSync(resolve(script));
   } catch {
-    return import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+    return moduleUrl === pathToFileURL(resolve(script)).href;
   }
 }
 

package/src/templates/design-kit-skill.md

@@ -0,0 +1,156 @@
+---
+name: design-kit
+description: "Draw mockups of this app's screens from its design kit: real pages and Storybook stories captured every day as static HTML, composed into self-contained pages with only the new parts hand-drawn. Use for any mockup, design or screen page of this app. Covers fetching the newest kit with gh, kit find/show/compose, <kit-snippet> and data-kit-new, staleness, captions saying what is real and what is new, and what to do when no kit can be fetched."
+---
+
+# Design kit
+
+Mockups of this app's screens start from its **design kit**: real pages of
+the app and its Storybook stories, rendered to static HTML with the app's own
+CSS and fonts, plus `kit.mjs`, a dependency-free tool that finds pieces and
+composes self-contained pages. Draw only what is new; the frame and every
+existing component come from the kit, so the mockup looks like the app it will
+ship in.
+
+The kit is configured in `{{CONFIG}}` and built by the `Design kit` workflow
+(`.github/workflows/design-kit.yml`). The format and every command are in the
+`{{PACKAGE}}` README.
+
+## 1. Fetch the newest kit
+
+The workflow runs once a day and on demand (`workflow_dispatch`), and uploads
+the `design-kit` artifact (kept 30 days). A day with no new commits skips and
+uploads nothing, yet still succeeds, so look up the newest artifact rather than
+the newest run, then download it once per kit commit:
+
+```bash
+REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
+BRANCH=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)
+read -r RUN SHA < <(gh api "repos/$REPO/actions/artifacts?name=design-kit&per_page=100" \
+  --jq "[.artifacts[] | select((.expired | not) and .workflow_run.head_branch == \"$BRANCH\")]
+        | sort_by(.created_at) | last // empty | \"\(.workflow_run.id) \(.workflow_run.head_sha)\"")
+echo "run=$RUN sha=$SHA"   # empty → go to "When there is no kit"
+KIT="${TMPDIR:-/tmp}/design-kit-$SHA"
+if [ -n "$RUN" ] && [ ! -f "$KIT/manifest.json" ]; then
+  rm -rf "$KIT.partial" &&
+    gh run download "$RUN" --repo "$REPO" -n design-kit -D "$KIT.partial" &&
+    mv "$KIT.partial" "$KIT"
+fi
+node "$KIT/kit.mjs" info   # manifest: sha, built_at, counts, sources
+```
+
+Reuse `$KIT` while the newest kit's SHA is unchanged. Keep the kit and your
+working files in a scratch folder, never in the repository.
+
+## 2. Check staleness
+
+The kit is a snapshot of `manifest.sha`, up to a day behind. Check whether UI
+code changed since:
+
+```bash
+KIT_SHA=$(node -p 'require(process.argv[1]).sha' "$KIT/manifest.json")
+git fetch -q origin "$BRANCH" && git log --oneline "$KIT_SHA..origin/$BRANCH" -- {{WATCHED_PATHS}}
+```
+
+When the list is not empty, say so on the mockup: "Kit from `<sha7>`; N UI
+commits since, so parts of the frame may be out of date". When one of those
+commits touches a component the mockup shows, read it and say what the mockup
+is missing.
+
+## 3. Find what is real
+
+```bash
+node "$KIT/kit.mjs" find button          # ≤ 30 lines: id, kind, width, bytes, title
+node "$KIT/kit.mjs" show route:home@1280 # path, size and an outline with slots
+```
+
+- **Frames** are whole screens: `route:<page>@<width>` rows, real pages of the
+  app at 1280 and 390 wide, with replaceable regions marked `data-kit-slot`
+  (`main` on every page). New content goes only into a slot, and only `route:`
+  frames have slots. A story frame is still useful unchanged, as the "today"
+  view or as real context beside a mockup.
+- **Snippets** are stories: `story:<storybook-id>@<width>`, one per component
+  state. Search by component and state (`find empty`, `find dialog`).
+- `show` prints a short outline. Use `show --full` only on a small snippet
+  whose structure you need, never on a frame.
+- Anything not in the kit has no story or its capture failed (`gaps.json` in
+  the kit lists the failures). Draw it as new and say it is approximated.
+
+## 4. Write only the new content
+
+Write one HTML fragment per slot you change, in your scratch folder:
+
+```html
+<!-- $WORK/after-main.html → fills the frame's `main` slot -->
+<div class="page">
+  <kit-snippet id="story:components-card--default@1280"></kit-snippet>
+  <section data-kit-new class="card">…only what the change adds…</section>
+</div>
+```
+
+- `<kit-snippet id="…">` places a real component; `compose` expands it with
+  the captured markup.
+- Mark every hand-drawn element with `data-kit-new` (the outermost new element
+  is enough).
+- Style new parts with the app's own classes and CSS variables. The kit's CSS
+  holds only the rules the app actually loads, so check a class exists with
+  `grep -c '\.<class>' "$KIT"/css/*.css`, or use an inline `style` with the
+  app's variables.
+- To show several states of the new part, stack them inside the fragment, each
+  with a short label.
+
+## 5. Compose
+
+```bash
+node "$KIT/kit.mjs" compose --frame route:home@1280 \
+  --slot main="$WORK/after-main.html" --out "$WORK/after-desktop.html"
+node "$KIT/kit.mjs" compose --frame route:home@1280 --out "$WORK/today.html"
+```
+
+The result is one self-contained page: CSS and fonts inlined, scripts and
+remote URLs removed, and `data-kit-sha` and `data-kit-id` on `<html>`. Add
+`--theme dark` for the dark theme and `--show-new` for a dashed outline on
+every `data-kit-new` element. An unknown frame, slot or snippet id exits 2 and
+names near matches.
+
+Never paste snippet or frame markup through your own output, and do not read a
+composed page back: it carries the whole CSS and fonts. Open it in a browser,
+screenshot it, and share the screenshot or the file.
+
+## 6. Caption: what is real, what is new
+
+Under every mockup, say which parts are real and which are new, and where you
+approximated:
+
+> Real: the Home page (`route:home@1280`) and the card
+> (`story:components-card--default@1280`), from kit `3f2a9c1` built
+> 2026-11-03. New (dashed): the Pinned section. Approximated: the pin menu has
+> no story yet.
+
+Add the staleness line from step 2 when it applies. For other widths, compose
+the capture on the same side of the breakpoint and say that layout decided in
+script stays as captured.
+
+## When there is no kit
+
+1. **Build it locally** from an up-to-date checkout with dependencies
+   installed (`{{INSTALL}}`):
+
+   ```bash
+   DK="{{CLI}}"
+   CONFIG="$PWD/{{CONFIG}}"
+   KIT="${TMPDIR:-/tmp}/design-kit-local-$(git rev-parse --short HEAD)"
+   {{PLAYWRIGHT_INSTALL}}
+   {{STORIES_LINE}}
+   $DK capture pages --config "$CONFIG" --out "$KIT"     # starts the app itself
+   ```
+
+   Then follow steps 3–6 with this `$KIT` and caption it as "local build at
+   `<sha7>`". A page capture that fails leaves a kit of stories only: compose
+   story frames unchanged for real context, draw the new screen by hand and
+   say so.
+
+2. **No kit at all**: approximate from the app's styles and components, and say
+   on every mockup "Approximated: the design kit was unavailable (<reason>)".
+
+Either way the work goes ahead; the caption says what you could not use.