@sableui/react 0.7.0 → 0.8.0

package/scripts/patches.mjs

@@ -0,0 +1,219 @@
+/**
+ * sable patch — fix a Sable component in place while the library fix ships, and
+ * hear about it on every upgrade.
+ *
+ * A defect in a component left an app two choices: restyle it with className,
+ * which `component-restyle` rightly flags, or wait for a release. A patch is the
+ * third: the project's own package manager patches the installed module
+ * (`pnpm patch`, `yarn patch`, or patch-package for npm), and this records why,
+ * against which version, and how to tell whether it is still needed:
+ *
+ *   .sable/patches.json  { patches: [{ component, files, version, base, reason, repro, issue? }] }
+ *
+ * `base` holds the hash of each file as Sable shipped it at that version
+ * (dist/file-hashes.json), so `sable doctor` can tell three things on a later
+ * install: whether the patch is applied, whether Sable has changed the file
+ * since, and what the changelog says about the component in between. A patch
+ * whose file Sable changed fails doctor (and so `sable check`) until someone
+ * re-runs the repro and keeps the patch or drops it. Nothing changes silently,
+ * in either direction.
+ */
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, parse, relative, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { packageManager } from "./agent-setup.mjs"
+import { parseFlags } from "./design-preferences.mjs"
+
+export const PATCHES_FILE = join(".sable", "patches.json")
+const PACKAGE = "@sableui/react"
+
+const hash = (path) => createHash("sha256").update(readFileSync(path)).digest("hex").slice(0, 16)
+
+/** Hashes of every dist file as published, written at build time. */
+function shippedHashes(pkgRoot) {
+	const path = join(pkgRoot, "dist", "file-hashes.json")
+	return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : null
+}
+
+export function readPatches(root) {
+	const path = join(root, PATCHES_FILE)
+	if (!existsSync(path)) return []
+	const data = JSON.parse(readFileSync(path, "utf8"))
+	if (!Array.isArray(data?.patches)) throw Object.assign(new Error(`${PATCHES_FILE} has no patches array.`), { code: "ERR_PATCHES_INVALID" })
+	return data.patches
+}
+
+function writePatches(root, patches) {
+	const path = join(root, PATCHES_FILE)
+	mkdirSync(dirname(path), { recursive: true })
+	writeFileSync(path, `${JSON.stringify({ patches }, null, 2)}\n`)
+}
+
+/**
+ * The dist modules a component's patch covers: its own folder's modules, not
+ * the barrel or the docs metadata. A part (CardList) resolves to its component.
+ */
+export function componentFiles(pkgRoot, name) {
+	const registry = JSON.parse(readFileSync(join(pkgRoot, "registry.json"), "utf8"))
+	const entries = [...(registry.components ?? []), ...(registry.layoutPrimitives?.primitives ?? [])]
+	const entry =
+		entries.find((c) => c.name === name) ??
+		entries.find((c) => (c.subcomponents ?? []).some((s) => s.name === name))
+	if (!entry?.path) return null
+	const dir = join(pkgRoot, "dist", entry.path)
+	if (!existsSync(dir)) return null
+	return {
+		component: entry.name,
+		files: readdirSync(dir)
+			.filter((f) => f.endsWith(".js") && f !== "index.js" && !f.endsWith(".meta.js"))
+			.map((f) => `dist/${entry.path}/${f}`),
+	}
+}
+
+/** Changelog bullets between two versions (exclusive, inclusive) that name the component. */
+export function changelogMentions(pkgRoot, component, from, to) {
+	const path = join(pkgRoot, "CHANGELOG.md")
+	if (!existsSync(path)) return []
+	const text = readFileSync(path, "utf8")
+	const out = []
+	for (const section of text.split(/^## /m).slice(1)) {
+		const version = section.split(/\s/, 1)[0]
+		if (compareVersions(version, from) <= 0 || compareVersions(version, to) > 0) continue
+		for (const bullet of section.split(/\n(?=- )/)) {
+			if (!bullet.startsWith("- ")) continue
+			if (!new RegExp(`\\b${component}\\b`).test(bullet)) continue
+			const lead = /^- \*\*(.+?)\*\*/.exec(bullet)?.[1] ?? bullet.slice(2, 120)
+			out.push(`${version}: ${lead.replace(/\s+/g, " ").replace(/\.$/, "")}`)
+		}
+	}
+	return out
+}
+
+function compareVersions(a, b) {
+	const x = String(a).split(/[.-]/).map((n) => Number(n) || 0)
+	const y = String(b).split(/[.-]/).map((n) => Number(n) || 0)
+	for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0) ? -1 : 1
+	return 0
+}
+
+/** How to make, commit and remove a patch with this project's package manager. */
+export function patchSteps(pm, version, files) {
+	const list = files.join(", ")
+	if (pm === "pnpm")
+		return {
+			make: [`pnpm patch ${PACKAGE}@${version}`, `edit ${list} in the folder it prints`, "pnpm patch-commit <that folder>"],
+			remove: [`pnpm patch-remove ${PACKAGE}@${version}`],
+		}
+	if (pm === "yarn")
+		return {
+			make: [`yarn patch ${PACKAGE}`, `edit ${list} in the folder it prints`, "yarn patch-commit -s <that folder>", "(Yarn 1: use the npm steps with patch-package)"],
+			remove: [`remove the patch: entry for ${PACKAGE} from package.json resolutions, then yarn install`],
+		}
+	return {
+		make: [`edit ${files.map((f) => `node_modules/${PACKAGE}/${f}`).join(", ")}`, `npx patch-package ${PACKAGE}`, 'add "postinstall": "patch-package" to package.json scripts'],
+		remove: [`delete patches/${PACKAGE.replace("/", "+")}+${version}.patch, then reinstall`],
+	}
+}
+
+/**
+ * One doctor check per recorded patch. `fail` when someone has to decide —
+ * Sable changed a patched file, or a patch is missing from the installed copy —
+ * so the agent is told on the upgrade itself, not when a user hits the bug.
+ */
+export function patchChecks(pkgRoot, root, installed) {
+	let patches
+	try {
+		patches = readPatches(root)
+	} catch (error) {
+		return [{ status: "fail", name: "patches", detail: error.message, fix: `Fix or delete ${PATCHES_FILE}.` }]
+	}
+	if (!patches.length) return []
+	const shipped = shippedHashes(pkgRoot)
+	if (!shipped) return [{ status: "warn", name: "patches", detail: `${patches.length} recorded, but this Sable build ships no file hashes to check them against.` }]
+	const pm = packageManager(parse(root).root, root)
+	return patches.map((p) => {
+		const name = `patch:${p.component}`
+		const why = `"${p.reason}"`
+		const missing = p.files.filter((f) => !shipped[f])
+		if (missing.length)
+			return { status: "fail", name, detail: `${p.version} → ${installed}: Sable no longer ships ${missing.join(", ")} (${why}). The component was restructured.`, fix: `Re-run the repro without the patch: ${p.repro}. Fixed → sable patch ${p.component} --drop. Still broken → patch the new files, then sable patch ${p.component} --keep.` }
+		const applied = p.files.some((f) => existsSync(join(pkgRoot, f)) && hash(join(pkgRoot, f)) !== shipped[f])
+		const changed = p.files.filter((f) => p.base?.[f] !== shipped[f])
+		const steps = patchSteps(pm, installed, p.files)
+		if (p.version === installed) {
+			if (applied) return { status: "pass", name, detail: `patched for ${why}${p.issue ? ` (${p.issue})` : ""}.` }
+			return { status: "warn", name, detail: `recorded for ${why} but not applied: the installed files are Sable's own.`, fix: steps.make.join(" → ") }
+		}
+		if (!changed.length && applied) return { status: "pass", name, detail: `patched for ${why}; Sable has not changed these files since ${p.version}.` }
+		const notes = changelogMentions(pkgRoot, p.component, p.version, installed)
+		const news = notes.length ? ` Changelog: ${notes.join(" | ")}.` : ""
+		if (!changed.length)
+			return { status: "fail", name, detail: `${p.version} → ${installed}: Sable did not change ${p.component}, and your patch (${why}) is not applied to ${installed}.`, fix: `Re-apply it: ${steps.make.join(" → ")}. Then sable patch ${p.component} --keep.` }
+		return {
+			status: "fail",
+			name,
+			detail: `${p.version} → ${installed}: Sable changed ${changed.join(", ")} since your patch (${why}).${news}`,
+			fix: `Re-run the repro on Sable's own files${applied ? " (remove the patch first)" : ""}: ${p.repro}. Fixed → sable patch ${p.component} --drop. Still broken → re-patch (${steps.make.join(" → ")}), then sable patch ${p.component} --keep, and report it.`,
+		}
+	})
+}
+
+/* ── CLI ────────────────────────────────────────────────────────────────────── */
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) {
+	const args = process.argv.slice(2)
+	const json = args.includes("--json")
+	const emit = (type, data, text) => process.stdout.write(json ? `${JSON.stringify({ type, data })}\n` : `${text}\n`)
+	try {
+		const pkgRoot = fileURLToPath(new URL("../", import.meta.url))
+		const root = process.cwd()
+		const installed = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8")).version
+		const name = args[0] && !args[0].startsWith("--") ? args[0] : null
+		const flags = parseFlags(name ? args.slice(1) : args, ["--reason", "--repro", "--issue", "--file"], ["--list", "--keep", "--drop", "--json"])
+		const patches = readPatches(root)
+		const pm = packageManager(parse(root).root, root)
+		if (flags.has("--list") || !name) {
+			const checks = patchChecks(pkgRoot, root, installed)
+			emit("patch.list", { patches, checks }, checks.length ? checks.map((c) => `${c.status === "pass" ? "✓" : c.status === "warn" ? "!" : "✗"} ${c.name} ${c.detail}${c.fix ? `\n    → ${c.fix}` : ""}`).join("\n") : "No Sable patches recorded.")
+		} else if (flags.has("--drop")) {
+			const p = patches.find((x) => x.component === name)
+			if (!p) throw Object.assign(new Error(`No recorded patch for ${name}.`), { code: "ERR_NO_PATCH" })
+			writePatches(root, patches.filter((x) => x !== p))
+			const steps = patchSteps(pm, p.version, p.files)
+			emit("patch.dropped", { component: name, remove: steps.remove }, `Dropped the ${name} patch record. Remove the patch itself too: ${steps.remove.join(" → ")}`)
+		} else if (flags.has("--keep")) {
+			const p = patches.find((x) => x.component === name)
+			if (!p) throw Object.assign(new Error(`No recorded patch for ${name}.`), { code: "ERR_NO_PATCH" })
+			const shipped = shippedHashes(pkgRoot) ?? {}
+			Object.assign(p, { version: installed, base: Object.fromEntries(p.files.map((f) => [f, shipped[f]])) })
+			writePatches(root, patches)
+			emit("patch.kept", p, `Kept the ${name} patch against ${installed}. Report it upstream if you haven't, so the library fix can replace it.`)
+		} else {
+			const reason = flags.get("--reason")
+			const repro = flags.get("--repro")
+			if (!reason || !repro)
+				throw Object.assign(new Error("A patch records why and how to check it: pass --reason \"<what is wrong>\" and --repro \"<how to see it>\"."), { code: "ERR_BAD_ARGUMENT" })
+			if (patches.some((x) => x.component === name)) throw Object.assign(new Error(`${name} already has a patch record. Use --keep or --drop.`), { code: "ERR_PATCH_EXISTS" })
+			const found = componentFiles(pkgRoot, name)
+			const extra = flags.get("--file")
+			if (!found && !extra) throw Object.assign(new Error(`No Sable component named ${name}. For a shared module, pass --file dist/lib/<module>.js.`), { code: "ERR_UNKNOWN_COMPONENT" })
+			const shipped = shippedHashes(pkgRoot) ?? {}
+			const files = [...(found?.files ?? []), ...(extra ? [extra.replace(/\\/g, "/")] : [])]
+			const unknown = files.filter((f) => !shipped[f])
+			if (unknown.length) throw Object.assign(new Error(`Not a published Sable file: ${unknown.join(", ")}.`), { code: "ERR_UNKNOWN_FILE" })
+			const record = { component: found?.component ?? name, files, version: installed, base: Object.fromEntries(files.map((f) => [f, shipped[f]])), reason, repro, ...(flags.get("--issue") ? { issue: flags.get("--issue") } : {}) }
+			writePatches(root, [...patches, record])
+			const steps = patchSteps(pm, installed, files)
+			emit(
+				"patch.recorded",
+				{ ...record, steps: steps.make },
+				`Recorded a patch for ${record.component} against ${installed} in ${relative(root, join(root, PATCHES_FILE))}.\nNow make it with ${pm}:\n${steps.make.map((s) => `  - ${s}`).join("\n")}\nOn every upgrade, sable doctor checks it: it fails when Sable changes these files, until the repro says keep (--keep) or drop (--drop).\nReport the defect upstream so the library fix can replace the patch.`,
+			)
+		}
+	} catch (error) {
+		process.stderr.write(`${JSON.stringify({ type: "error", code: error.code ?? "ERR_PATCH", message: error.message, suggestions: ["sable patch --list", "sable docs patching-a-component"] })}\n`)
+		process.exitCode = 1
+	}
+}

package/scripts/sources.mjs

@@ -0,0 +1,247 @@
+/**
+ * sable sources — point Tailwind at the Sable modules an app actually imports.
+ *
+ * The install recipe's `@source` covers the whole published `dist`, so Tailwind
+ * generates every component's classes whether the app renders it or not:
+ * Sable's own stylesheet is about 6 KB gzipped, and the whole-dist scan takes an
+ * app to about 32 KB. A support app measured that, a third more CSS than the
+ * same app on shadcn.
+ *
+ * This follows the app's imports from `@sableui/react` (and its subpaths)
+ * through the published module graph — each name to the module that defines it,
+ * then every module that one imports, static and lazy — and writes one
+ * `@source` per module. The app's own files are Tailwind's to find as before.
+ *
+ * The cost is that the list goes stale when the app imports something new, and
+ * a component missing from it renders unstyled without an error. So the file
+ * says where it came from, and `sable doctor` (and `sable check`) recompute it
+ * and fail when a module the app needs is not covered.
+ */
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { dirname, join, relative, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const SOURCES_MARKER = "Generated by sable sources"
+const SKIP = new Set(["node_modules", "dist", "build", "out", ".next", ".git", "coverage", ".turbo"])
+
+/** `@sableui/react[/sub]` specifier → the published module, from the package's exports map. */
+function entryFor(pkgRoot, specifier) {
+	const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"))
+	const exports = pkg.publishConfig?.exports ?? pkg.exports ?? {}
+	const key = specifier === "@sableui/react" ? "." : `.${specifier.slice("@sableui/react".length)}`
+	const target = exports[key]
+	const path = typeof target === "string" ? target : target?.default ?? target?.import
+	if (!path || !path.endsWith(".js")) return null
+	const file = join(pkgRoot, path)
+	return existsSync(file) ? file : null
+}
+
+const moduleCache = new Map()
+/** A module's imports and exports, read lexically from the bundler's plain ESM output. */
+function parseModule(file) {
+	if (moduleCache.has(file)) return moduleCache.get(file)
+	const text = readFileSync(file, "utf8")
+	const rel = (spec) => resolve(dirname(file), spec)
+	const names = (list) =>
+		list
+			.split(",")
+			.map((s) => s.trim())
+			.filter(Boolean)
+			.map((s) => {
+				const [from, as] = s.split(/\s+as\s+/)
+				return { from: from.trim(), as: (as ?? from).trim() }
+			})
+	const imports = new Map() // local → { file, name }
+	for (const m of text.matchAll(/import\s*\{([^}]*)\}\s*from\s*"(\.[^"]+)"/g))
+		for (const n of names(m[1])) imports.set(n.as, { file: rel(m[2]), name: n.from })
+	const reexports = new Map() // exported → { file, name }
+	const local = new Set()
+	const stars = []
+	for (const m of text.matchAll(/export\s*\{([^}]*)\}\s*from\s*"(\.[^"]+)"/g))
+		for (const n of names(m[1])) reexports.set(n.as, { file: rel(m[2]), name: n.from })
+	for (const m of text.matchAll(/export\s*\*\s*from\s*"(\.[^"]+)"/g)) stars.push(rel(m[1]))
+	for (const m of text.matchAll(/export\s*\{([^}]*)\}\s*(?:;|\n|$)/g))
+		for (const n of names(m[1])) {
+			if (imports.has(n.from)) reexports.set(n.as, imports.get(n.from))
+			else local.add(n.as)
+		}
+	for (const m of text.matchAll(/export\s+(?:async\s+)?(?:function\*?|const|let|var|class)\s+([\w$]+)/g)) local.add(m[1])
+	const deps = [
+		...[...text.matchAll(/(?:import|export)\s[^"']*?from\s*"(\.[^"]+)"/g)].map((m) => rel(m[1])),
+		...[...text.matchAll(/import\s*"(\.[^"]+)"/g)].map((m) => rel(m[1])),
+		...[...text.matchAll(/import\(\s*"(\.[^"]+)"\s*\)/g)].map((m) => rel(m[1])),
+	]
+	const parsed = { local, reexports, stars, deps }
+	moduleCache.set(file, parsed)
+	return parsed
+}
+
+/** The module that defines `name`, following re-exports and `export *`. */
+function definingModule(file, name, seen = new Set()) {
+	if (seen.has(file) || !existsSync(file)) return null
+	seen.add(file)
+	const m = parseModule(file)
+	if (m.local.has(name)) return file
+	const re = m.reexports.get(name)
+	if (re) return definingModule(re.file, re.name, seen)
+	for (const star of m.stars) {
+		const hit = definingModule(star, name, seen)
+		if (hit) return hit
+	}
+	return null
+}
+
+/** Every module reachable from `roots` by relative import. */
+function closure(roots) {
+	const out = new Set()
+	const stack = [...roots]
+	while (stack.length) {
+		const file = stack.pop()
+		if (out.has(file) || !existsSync(file)) continue
+		out.add(file)
+		stack.push(...parseModule(file).deps)
+	}
+	return out
+}
+
+/** The app's source files, outside dependencies and build output. */
+export function appSources(root) {
+	const out = []
+	const walk = (dir) => {
+		let entries
+		try {
+			entries = readdirSync(dir)
+		} catch {
+			return
+		}
+		for (const name of entries) {
+			if (SKIP.has(name) || name.startsWith(".")) continue
+			const full = join(dir, name)
+			const st = statSync(full)
+			if (st.isDirectory()) walk(full)
+			else if (/\.(?:[cm]?[jt]sx?)$/.test(name) && !/\.d\.ts$/.test(name)) out.push(full)
+		}
+	}
+	walk(root)
+	return out
+}
+
+/**
+ * The published modules an app's imports reach. `unresolved` lists what could
+ * not be traced (a namespace import, a name the package does not export); any
+ * of those means the whole package is needed.
+ */
+export function sableModules(pkgRoot, files) {
+	const roots = new Set()
+	const unresolved = []
+	const spec = /(?:import|export)\s+(type\s+)?([^;"'`]*?)\s*from\s*["'](@sableui\/react(?:\/[\w./-]+)?)["']|import\(\s*["'](@sableui\/react(?:\/[\w./-]+)?)["']\s*\)/g
+	for (const path of files) {
+		const text = readFileSync(path, "utf8")
+		for (const m of text.matchAll(spec)) {
+			if (m[1]) continue // `import type` brings no runtime module
+			const specifier = m[3] ?? m[4]
+			if (/\.css$/.test(specifier)) continue
+			const entry = entryFor(pkgRoot, specifier)
+			if (!entry) {
+				unresolved.push(specifier)
+				continue
+			}
+			const clause = m[2] ?? ""
+			const braces = /\{([^}]*)\}/.exec(clause)?.[1]
+			// A namespace import, a default import, `export *` or a dynamic import
+			// can reach anything the entry exports.
+			if (m[4] || /\*/.test(clause) || !braces || /^\s*[\w$]+\s*(?:,|$)/.test(clause)) {
+				roots.add(entry)
+				if (!braces) continue
+			}
+			for (const part of braces.split(",")) {
+				const name = part.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim()
+				if (!name || /^type\s/.test(part.trim())) continue
+				const file = definingModule(entry, name)
+				if (file) roots.add(file)
+				else unresolved.push(`${name} from ${specifier}`)
+			}
+		}
+	}
+	// A component's .meta.js is its docs: class names there are example strings,
+	// never rendered, and a barrel import would otherwise ship them all.
+	return { modules: [...closure(roots)].filter((f) => !f.endsWith(".meta.js")).sort(), unresolved }
+}
+
+/** Where the app reaches the package: its own node_modules link when there is one. */
+function packageBase(pkgRoot, root) {
+	const linked = join(root, "node_modules", "@sableui", "react")
+	return existsSync(join(linked, "package.json")) ? linked : pkgRoot
+}
+
+export function sourcesCss(pkgRoot, root, outFile) {
+	const { modules, unresolved } = sableModules(pkgRoot, appSources(root))
+	const base = packageBase(pkgRoot, root)
+	const from = dirname(resolve(root, outFile))
+	const line = (file) => `@source "${relative(from, join(base, relative(pkgRoot, file))).split("\\").join("/")}";`
+	const body = unresolved.length ? [line(join(pkgRoot, "dist")).replace(/";$/, '/**/*.{js,mjs}";')] : modules.map(line)
+	const css = [
+		`/* ${SOURCES_MARKER}: the @sableui/react modules this app imports, so Tailwind`,
+		"   generates their classes and no others. Re-run `sable sources --write` after",
+		"   importing something new from Sable; `sable check` fails while it is stale. */",
+		...body,
+		"",
+	].join("\n")
+	return { css, modules, unresolved }
+}
+
+/**
+ * Doctor: a sources file that is missing a module the app now imports renders
+ * that component unstyled, silently — so it fails. A whole-package @source is
+ * correct, just heavy, so it only gets a note.
+ */
+export function sourcesCheck(pkgRoot, root, cssFiles) {
+	const generated = cssFiles.find((f) => f.text.includes(SOURCES_MARKER))
+	if (!generated) {
+		const whole = cssFiles.some((f) => /@source[^;]*(?:@sableui\/react|packages\/sable)\/dist(?:\/\*\*)?[^;]*;/.test(f.text))
+		return whole ? [{ status: "info", name: "css:size", detail: "@source scans all of Sable's dist, so every component's classes ship (about 32 KB gzipped).", fix: "sable sources --write src/sable-sources.css, then import it in place of that @source." }] : []
+	}
+	const rel = relative(root, generated.path)
+	const { modules, unresolved } = sableModules(pkgRoot, appSources(root))
+	if (unresolved.length && !/\/dist\/\*\*\//.test(generated.text))
+		return [{ status: "fail", name: "css:sources", detail: `${rel} lists modules, but these imports could not be traced: ${unresolved.slice(0, 4).join(", ")}.`, fix: `sable sources --write ${rel}` }]
+	const base = packageBase(pkgRoot, root)
+	const covered = new Set(
+		[...generated.text.matchAll(/@source\s+"([^"]+)"/g)].map((m) => resolve(dirname(generated.path), m[1])),
+	)
+	const wholeDist = [...covered].some((p) => /[\\/]dist[\\/]\*\*/.test(p))
+	if (wholeDist) return [{ status: "pass", name: "css:sources", detail: `${rel} covers all of Sable.` }]
+	const missing = modules.filter((file) => !covered.has(join(base, relative(pkgRoot, file))))
+	if (missing.length)
+		return [{ status: "fail", name: "css:sources", detail: `${rel} is stale: ${missing.length} module(s) the app now imports are not in it (${missing.slice(0, 3).map((f) => relative(join(pkgRoot, "dist"), f).split("\\").join("/")).join(", ")}${missing.length > 3 ? ", …" : ""}). Their components render unstyled.`, fix: `sable sources --write ${rel}` }]
+	return [{ status: "pass", name: "css:sources", detail: `${rel} covers the ${modules.length} Sable modules the app imports.` }]
+}
+
+/* ── CLI ────────────────────────────────────────────────────────────────────── */
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) {
+	const args = process.argv.slice(2)
+	const json = args.includes("--json")
+	try {
+		const pkgRoot = fileURLToPath(new URL("../", import.meta.url))
+		const root = process.cwd()
+		const at = args.indexOf("--write")
+		const out = at === -1 ? null : args[at + 1]
+		if (at !== -1 && (!out || out.startsWith("--"))) throw Object.assign(new Error("--write needs a stylesheet path, e.g. src/sable-sources.css."), { code: "ERR_BAD_ARGUMENT" })
+		const unknown = args.filter((a, i) => a.startsWith("--") && !["--write", "--json"].includes(a) && args[i - 1] !== "--write")
+		if (unknown.length) throw Object.assign(new Error(`Unknown flag: ${unknown[0]}`), { code: "ERR_BAD_FLAG" })
+		const target = out ?? "src/sable-sources.css"
+		const result = sourcesCss(pkgRoot, root, target)
+		if (out) writeFileSync(resolve(root, out), result.css)
+		const note = result.unresolved.length
+			? `Could not trace ${result.unresolved.slice(0, 4).join(", ")}, so it covers all of Sable.`
+			: `${result.modules.length} modules.`
+		if (json) process.stdout.write(`${JSON.stringify({ type: "sources", data: { file: out, modules: result.modules.length, unresolved: result.unresolved, css: result.css } })}\n`)
+		else if (out) process.stdout.write(`Wrote ${out}: ${note}\nImport it in your stylesheet in place of the whole-package @source:\n  @import "./${relative(dirname(resolve(root, "src/app.css")), resolve(root, out)).split("\\").join("/")}";\n`)
+		else process.stdout.write(result.css)
+	} catch (error) {
+		process.stderr.write(`${JSON.stringify({ type: "error", code: error.code ?? "ERR_SOURCES", message: error.message, suggestions: ["sable sources --write src/sable-sources.css"] })}\n`)
+		process.exitCode = 1
+	}
+}

package/skills/sable/SKILL.md

@@ -157,12 +157,21 @@ The installed catalog and guides are authoritative for API and token names.
 ## Develop or use a preset
 
 Save a short brief in the project's existing design location: audience, primary
-task, content, constraints, selected identity, and meaningful states. Label invented
-sample content. A supplied preset is an explicit input: read its exact record and
+task, content, constraints, selected identity, and meaningful states, plus each
+route's width (a Region `max`, or fluid) and why, chosen by what the person does
+there (`sable docs building-a-page`). Label invented sample content. A supplied preset is an explicit input: read its exact record and
 revision, validate it through `sable preset --check <path> --json`, and read
 `sable docs using-presets`. Preserve its tokens and guidance unless the user requests
 a change or the new task requires a documented adaptation.
 
+A preset pasted or supplied for a project that already has an app (for example
+from Canvas's “Copy for agent”) is a request to restyle that app, so it is
+`polish`: save and check it, then apply it. Generate its CSS, load its fonts,
+make it SableThemeProvider's default theme and mode in place of the old one, run
+the build and the finish checklist, and look at it rendered. Don't stop at a saved
+file plus a list of wiring steps for the user. Stop after saving only when the
+user says so or the project has no app yet.
+
 Without a preset, develop an appropriate direction from the brief. Use the bundled
 presets as starting points or create original app-owned tokens. When the project has
 its own visual atlas, retrieve references with `sable atlas --search "<problem>"
@@ -218,6 +227,9 @@ Every build ends with the finish checklist at the top of this skill. Notes on it
   the smallest necessary addition, and include the inventory with the build's
   evidence so conformance is reviewable.
 
-Iterate on observed defects and recapture changed states. Contract checks cannot
-judge beauty. Deliver the result, the preset/revision used, the checks performed,
+Iterate on observed defects and recapture changed states. A defect inside a Sable
+component is patched, not restyled: `sable patch <Component> --reason … --repro …`,
+then the package manager's patch (`sable docs patching-a-component`). When `sable
+doctor` fails on a patch after an upgrade, re-run its repro on Sable's own files
+and keep or drop it. Contract checks cannot judge beauty. Deliver the result, the preset/revision used, the checks performed,
 and material limitations.