spool.page 0.0.0

package/README.md

@@ -0,0 +1,7 @@
+# spool
+
+A canvas where the frames are alive.
+
+Agent-authored TSX frames on an infinite canvas: arrange them spatially, link them into walkable flows, and feel an app (interactions, motion, state, real inputs) before it exists. Code is the document; the canvas is a projection of it. A design space is just a `design/` folder inside your product repo: local-first, git-tracked, no cloud.
+
+Home: [spool.page](https://spool.page). Status: wayfinding. The map lives in this repo's issues (`wayfinder:map`); exploration research lives in `research/`.

package/dist/cli.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { homedir } from "os";
+import { basename, join as join4 } from "path";
+import { Command } from "commander";
+
+// src/errors.ts
+var SpoolError = class extends Error {
+  name = "SpoolError";
+};
+
+// src/init.ts
+import { existsSync, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+
+// src/paths.ts
+import { realpathSync } from "fs";
+import { resolve } from "path";
+function realDir(dir) {
+  try {
+    return realpathSync(resolve(dir));
+  } catch {
+    throw new SpoolError(`no such directory: ${dir}`);
+  }
+}
+
+// src/registry.ts
+import { mkdirSync, readFileSync, realpathSync as realpathSync2, renameSync, writeFileSync } from "fs";
+import { join } from "path";
+function readRegistry(spoolDir2) {
+  const file = join(spoolDir2, "registry.json");
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { version: 1, projects: [] };
+    }
+    throw new SpoolError(`cannot read registry at ${file}: ${error.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    parsed = void 0;
+  }
+  if (!isRegistry(parsed)) {
+    throw new SpoolError(`corrupt registry at ${file}, fix or remove it`);
+  }
+  return parsed;
+}
+function registerProject(spoolDir2, root) {
+  const real = realpathSync2(root);
+  const registry = readRegistry(spoolDir2);
+  const openedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const existing = registry.projects.find((p) => p.root === real);
+  if (existing) {
+    existing.openedAt = openedAt;
+  } else {
+    registry.projects.push({ root: real, openedAt });
+  }
+  writeRegistry(spoolDir2, registry);
+}
+function isRegistry(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  if (record.version !== 1 || !Array.isArray(record.projects)) return false;
+  return record.projects.every((project) => {
+    if (typeof project !== "object" || project === null) return false;
+    const p = project;
+    return typeof p.root === "string" && typeof p.openedAt === "string";
+  });
+}
+function writeRegistry(spoolDir2, registry) {
+  mkdirSync(spoolDir2, { recursive: true });
+  const file = join(spoolDir2, "registry.json");
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(registry, null, "	")}
+`);
+  renameSync(tmp, file);
+}
+
+// src/templates.ts
+var FORMAT_VERSION = 1;
+var canvasJson = `${JSON.stringify({ format: FORMAT_VERSION }, null, "	")}
+`;
+var gitignore = ".spool/\n";
+var claudeMd = "@AGENTS.md\n";
+var agentsMd = `# spool canvas
+
+This folder is a [spool](https://spool.page) project: live TSX frames on an infinite canvas, authored by agents, arranged and played by humans.
+
+- A frame is born by writing \`frames/<name>/frame.tsx\` default-exporting one React component. No registration step, no \`spool new\`.
+- Variants are sibling frames named with \`--\`, like \`checkout--empty/\`.
+- Shared code lives in \`shared/\`: \`ui/\` components (props only, never import \`"spool"\`), \`lib/utils.ts\` with \`cn()\`, \`tokens.css\`, \`scenarios/\`, \`fixtures/\`.
+- Run \`spool skill\` for the complete contract. If it is not in there, spool does not do it.
+- \`canvas.json\` and \`.spool/\` are app-owned. Never edit them.
+`;
+var tokensCss = `/*
+ * spool tokens, the single token file for this canvas.
+ * Distilling from an existing product: paste its variables into :root verbatim.
+ * Spool-born tokens: use @theme (Tailwind v4, shadcn v4 shape).
+ * Starts empty on purpose: tokens arrive per change, carried by the agent.
+ */
+:root {}
+`;
+var transitionsCss = `/*
+ * Player transition styling, plain CSS (no Tailwind here).
+ * Crossfade is the default. For morphs, give elements a shared
+ * view-transition-name in their frames and style ::view-transition-* here.
+ */
+`;
+var fontsCss = `/*
+ * Project fonts, plain CSS: @font-face rules or a Google Fonts @import.
+ * Font files live in shared/assets/fonts/. Loaded in every frame document.
+ */
+`;
+var importmapJson = `{
+	"imports": {
+		"class-variance-authority": "https://esm.sh/class-variance-authority@0.7.1",
+		"clsx": "https://esm.sh/clsx@2.1.1",
+		"motion": "https://esm.sh/motion@12.42.2?external=react,react-dom",
+		"motion/react": "https://esm.sh/motion@12.42.2/react?external=react,react-dom",
+		"tailwind-merge": "https://esm.sh/tailwind-merge@3.6.0"
+	}
+}
+`;
+var defaultScenario = `{
+	"state": {},
+	"mock": {}
+}
+`;
+var utilsTs = `import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}
+`;
+var scaffoldFiles = {
+  ".gitignore": gitignore,
+  "AGENTS.md": agentsMd,
+  "CLAUDE.md": claudeMd,
+  "canvas.json": canvasJson,
+  "shared/tokens.css": tokensCss,
+  "shared/transitions.css": transitionsCss,
+  "shared/fonts.css": fontsCss,
+  "shared/importmap.json": importmapJson,
+  "shared/scenarios/default.json": defaultScenario,
+  "shared/lib/utils.ts": utilsTs
+};
+var scaffoldDirs = ["frames", "shared/ui", "shared/fixtures", "shared/assets/fonts"];
+
+// src/init.ts
+function initProject(targetDir, spoolDir2) {
+  const root = realDir(targetDir);
+  const design = join2(root, "design");
+  if (existsSync(join2(design, "canvas.json"))) {
+    throw new SpoolError(`already a spool project: ${root} (run \`spool open\` instead)`);
+  }
+  if (existsSync(design)) {
+    throw new SpoolError(`design/ already exists at ${root} and is not a spool project, move it aside first`);
+  }
+  for (const dir of scaffoldDirs) {
+    mkdirSync2(join2(design, dir), { recursive: true });
+  }
+  for (const [rel, content] of Object.entries(scaffoldFiles)) {
+    const file = join2(design, rel);
+    mkdirSync2(dirname(file), { recursive: true });
+    writeFileSync2(file, content);
+  }
+  registerProject(spoolDir2, root);
+  return { root };
+}
+
+// src/resolve.ts
+import { existsSync as existsSync2 } from "fs";
+import { dirname as dirname2, join as join3 } from "path";
+function resolveProjectRoot(startDir) {
+  let dir = realDir(startDir);
+  let prev = "";
+  while (dir !== prev) {
+    if (existsSync2(join3(dir, "design", "canvas.json"))) return dir;
+    prev = dir;
+    dir = dirname2(dir);
+  }
+  return void 0;
+}
+
+// src/open.ts
+function openProject(startDir, spoolDir2) {
+  const root = resolveProjectRoot(startDir);
+  if (root === void 0) {
+    throw new SpoolError(`no spool project found from ${startDir}, run \`spool init\` in your product root`);
+  }
+  registerProject(spoolDir2, root);
+  return { root };
+}
+
+// src/cli.ts
+var pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
+var spoolDir = join4(homedir(), ".spool");
+var rootConfigPointer = `add this line to the repo's root CLAUDE.md or AGENTS.md so future sessions find the canvas:
+
+  design/ is a spool canvas (see design/AGENTS.md; run \`spool skill\` to learn it)
+`;
+var program = new Command("spool").description("the live prototyping canvas").version(pkg.version, "-v, --version");
+program.command("init").description("scaffold design/ in a product root and register it").argument("[path]", "product root", ".").action((path) => {
+  const { root } = initProject(path, spoolDir);
+  process.stdout.write(`initialized spool project at ${root}
+
+${rootConfigPointer}`);
+});
+program.command("open").description("resolve the project by walk-up and register it").argument("[path]", "where the walk-up starts", ".").action((path) => {
+  const { root } = openProject(path, spoolDir);
+  process.stdout.write(`registered ${basename(root)} (${root})
+`);
+});
+try {
+  program.parse();
+} catch (error) {
+  if (error instanceof SpoolError) {
+    process.stderr.write(`spool: ${error.message}
+`);
+    process.exitCode = 1;
+  } else {
+    throw error;
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "spool.page",
+	"version": "0.0.0",
+	"description": "Live prototyping canvas: agent-authored TSX frames on an infinite canvas, repo-native.",
+	"repository": "github:devosurf/spool",
+	"type": "module",
+	"bin": {
+		"spool": "./dist/cli.js"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"packageManager": "pnpm@11.5.3",
+	"scripts": {
+		"dev": "tsx src/cli.ts",
+		"build": "tsup",
+		"prepack": "tsup",
+		"typecheck": "tsc --noEmit",
+		"check": "biome check .",
+		"test": "vitest run"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.5",
+		"@types/node": "^22.20.1",
+		"tsup": "^8.5.1",
+		"tsx": "^4.23.1",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.10"
+	},
+	"dependencies": {
+		"commander": "^15.0.0"
+	}
+}