@sableui/react 0.17.0 → 0.19.0

package/scripts/adoption.mjs

@@ -0,0 +1,252 @@
+/**
+ * adoption — how much of an app's UI is actually built from Sable.
+ *
+ * Wiring can be perfect while the app composes none of it: an agent that never
+ * loaded the skill sees Tailwind and a stylesheet and writes its own Button, its
+ * own Modal, its own Tabs on top of Sable's tokens. Lint catches a raw
+ * `<button>` with classes; it cannot see that `function Modal()` is a dialog
+ * Sable already ships, or that forty UI files import nothing from the package.
+ *
+ * This reads the source lexically, like grade, and answers three things:
+ *
+ *   - level: how many UI files compose Sable at all
+ *   - swaps: app-defined components named for something Sable ships, which the
+ *            file does not itself build on (behaviour first: those are where
+ *            focus, keyboard and ARIA bugs live)
+ *   - foundation: "sable" when Sable already carries the UI; otherwise whether
+ *            the app has its own system to respect (another UI library, or a
+ *            folder of its own primitives) or is ad hoc
+ *
+ * It never fails anything. It is the evidence an agent shows the user when it
+ * asks whether to move app-built UI onto Sable, and the wording of that ask
+ * depends on the foundation: firm when there is none, gentle when there is one.
+ */
+
+/** Groups whose components own behaviour (focus, keyboard, ARIA). */
+const BEHAVIOUR_GROUPS = new Set(["Actions", "Forms", "Overlays", "Navigation", "Selection"])
+const BEHAVIOUR_NAMES = new Set(["Accordion", "Collapsible", "Carousel", "Toast", "DataTable", "CommandMenu"])
+
+/** Other component libraries, by import specifier. */
+const LIBRARIES = [
+	[/^@mui\//, "MUI"],
+	[/^@chakra-ui\//, "Chakra UI"],
+	[/^antd(?:$|\/)/, "Ant Design"],
+	[/^@mantine\//, "Mantine"],
+	[/^react-bootstrap(?:$|\/)/, "React Bootstrap"],
+	[/^@headlessui\//, "Headless UI"],
+	[/^@radix-ui\//, "Radix"],
+	[/^@(?:nextui-org|heroui)\//, "HeroUI"],
+	[/^(?:react-aria-components$|@react-aria\/)/, "React Aria"],
+	[/^primereact(?:$|\/)/, "PrimeReact"],
+	[/^flowbite-react(?:$|\/)/, "Flowbite"],
+	[/^@ark-ui\//, "Ark UI"],
+]
+/** shadcn/ui-style primitives: `@/components/ui/button`, `../components/ui/dialog`. */
+const SHADCN = /(?:^|\/)components\/ui\/[a-z][\w-]*$/
+/** Where an app keeps a system of its own. */
+const PRIMITIVES_DIR = /(?:^|\/)(?:ui|primitives|design-system|ds)\//i
+/** Names that are an app's own structure, never a control it rebuilt. */
+const STRUCTURAL = /^(?:App|Root|Main|Home|Index)$|(?:Page|Layout|Provider|Context|Screen|View|Routes?|Router|Story|Stories|Demo|Example|Icon|Logo)$/
+
+const IMPORT = /import\s+(?:type\s+)?([\s\S]*?)\s+from\s*["']([^"']+)["']/g
+const DECLARATIONS = [
+	/(?:^|\n)[ \t]*(?:export\s+(?:default\s+)?)?function\s+([A-Z]\w*)\s*[(<]/g,
+	/(?:^|\n)[ \t]*(?:export\s+)?const\s+([A-Z]\w*)\s*(?::[^=\n]+)?=\s*(?:React\.)?(?:forwardRef|memo)\b/g,
+	/(?:^|\n)[ \t]*(?:export\s+)?const\s+([A-Z]\w*)\s*(?::[^=\n]+)?=\s*(?:async\s*)?\([^)]*\)\s*(?::[^=\n]+)?=>/g,
+]
+
+const normalize = (s) => s.toLowerCase().replace(/[\s_-]+/g, "")
+const words = (name) => name.match(/[A-Z]+(?![a-z])|[A-Z]?[a-z0-9]+/g) ?? [name]
+/**
+ * Behaviour done by hand, on native elements: what makes a component named
+ * Modal or Tabs a rebuild rather than content handed to Sable's (a tooltip
+ * body for ActivityHeatmap) or a composition of Sable's own controls (a
+ * toolbar of Pill, Select and SearchInput). Handlers on a capitalised tag
+ * belong to that component, so only lowercase tags count.
+ */
+const HAND_BEHAVIOUR = [
+	/<(?:button|input|select|textarea|dialog|details)\b/,
+	/<[a-z][a-z0-9]*\b[^<>]*\son(?:Click|KeyDown|KeyUp|MouseEnter|MouseLeave|PointerDown|PointerEnter|Focus|Blur)\s*=/,
+	/<[a-z][a-z0-9]*\b[^<>]*\srole=["'](?:dialog|alertdialog|tablist|tab|tabpanel|menu|menubar|menuitem|listbox|option|combobox|switch|slider|tooltip|checkbox|radio|radiogroup)["']/,
+	/<[a-z][a-z0-9]*\b[^<>]*\saria-(?:expanded|modal|selected|haspopup|pressed|checked)=/,
+	/\bcreatePortal\s*\(/,
+	/className=["'`][^"'`]*\bfixed\b[^"'`]*\binset-/,
+]
+const isBehaviour = (c) => BEHAVIOUR_GROUPS.has(c.group) || BEHAVIOUR_NAMES.has(c.name)
+const lineOf = (text, index) => text.slice(0, index).split("\n").length
+
+/**
+ * A .tsx/.jsx file that renders markup: a closing tag, or a self-closing `/>`
+ * (matched bare, since an arrow handler's `=>` sits inside the tag).
+ */
+const rendersJsx = (text) => /<\/[A-Za-z][\w.]*\s*>|\/>/.test(text)
+
+/**
+ * The names apps give the controls they rebuild, mapped to Sable's. Curated
+ * rather than read from registry keywords: those are written for search, so
+ * "list", "panel" and "preview" tie half an app's own components to something.
+ */
+const ALIASES = {
+	modal: ["Dialog"], dropdown: ["Menu", "Select"], dropdownmenu: ["Menu"], popup: ["Popover"],
+	drawer: ["Sheet"], sidesheet: ["Sheet"], bottomsheet: ["Sheet"], snackbar: ["Toast"], notification: ["Toast"],
+	spinner: ["Spinner"], loader: ["Spinner", "Skeleton"], progressbar: ["Progress"], autocomplete: ["Combobox"],
+	typeahead: ["Combobox"], multiselect: ["Combobox"], textfield: ["Input"], textinput: ["Input"], searchbar: ["SearchInput"],
+	searchbox: ["SearchInput"], searchfield: ["SearchInput"], iconbutton: ["Button"], fileupload: ["FileDropzone"],
+	uploader: ["FileDropzone"], dropzone: ["FileDropzone"], collapse: ["Collapsible"], disclosure: ["Collapsible"],
+	commandpalette: ["CommandMenu"], datepicker: ["DatePicker"], toggleswitch: ["Switch"], segmentedcontrol: ["Tabs", "ButtonGroup"],
+	tabbar: ["Tabs", "BottomNav"], navbar: ["AppHeader", "NavigationMenu"], topbar: ["AppHeader"], breadcrumb: ["Breadcrumbs"],
+	chip: ["Pill", "Badge"], tag: ["Badge"], alert: ["Banner"], callout: ["Note"], confirmdialog: ["DestructiveActionModal", "Dialog"],
+	contextmenu: ["ContextMenu"], hovercard: ["ContextCard"], numberinput: ["NumberField"], otpinput: ["OtpField"], pininput: ["OtpField"],
+	colorpicker: ["ColorField"], rating: ["RadioCard"], stepper: ["Stepper"], wizard: ["Stepper"], kbd: ["Kbd"],
+	property: ["PropertyRow"], propertyrow: ["PropertyRow"], proprow: ["PropertyRow"], picker: ["Select", "Combobox"],
+	statusmark: ["StatusDot"], statusindicator: ["StatusDot"], presencedot: ["StatusDot"], avatarstack: ["AvatarGroup"],
+	facepile: ["AvatarGroup"], topnav: ["WorkspaceBar", "AppHeader"], appbar: ["WorkspaceBar", "AppHeader"],
+	headerbar: ["WorkspaceBar", "AppHeader"], themetoggle: ["ThemeSwitcher"], modetoggle: ["ThemeSwitcher"],
+	darkmodetoggle: ["ThemeSwitcher"], colormodeswitch: ["ThemeSwitcher"],
+}
+
+/**
+ * The Sable components an app-defined name stands for: its whole name or its
+ * last word or two, as a Sable name (`Button`, `PrimaryButton`) or an alias
+ * (`Modal`, `SearchModal` → Dialog).
+ */
+function matcher(components) {
+	const byName = new Map(components.map((c) => [c.name.toLowerCase(), c]))
+	// Parts count: `PropertyRow`, `WorkspaceBar` and `AvatarGroup` are exported
+	// names an app's `Property` or `TeamAvatars` stands in for. A part inherits
+	// its entry's group, so a part of a behaviour component is behaviour too.
+	for (const c of components)
+		for (const s of c.subcomponents ?? []) {
+			const name = typeof s === "string" ? s : s.name
+			if (name && !byName.has(name.toLowerCase())) byName.set(name.toLowerCase(), { name, group: c.group, partOf: c.name })
+		}
+	return (appName) => {
+		if (STRUCTURAL.test(appName)) return []
+		const w = words(appName)
+		const candidates = [...new Set([appName, w.slice(-2).join(""), w.at(-1)].filter(Boolean).map(normalize))]
+		for (const key of candidates) {
+			if (byName.has(key)) return [byName.get(key)]
+			const alias = ALIASES[key]?.map((name) => byName.get(name.toLowerCase())).filter(Boolean)
+			if (alias?.length) return alias
+		}
+		return []
+	}
+}
+
+/**
+ * @param {{ files: { rel: string, text: string }[], components: object[], deps?: Record<string, string> | null }} input
+ *   files: the app's .tsx/.jsx sources, paths relative to the project.
+ */
+export function adoptionReport({ files, components, deps = null }) {
+	const match = matcher(components)
+	const sableUsed = new Set()
+	const libraries = new Map()
+	let uiFiles = 0
+	let sableFiles = 0
+	let ownPrimitives = 0
+	const swaps = []
+
+	for (const { rel, text } of files) {
+		if (!/\.(tsx|jsx)$/.test(rel) || !rendersJsx(text)) continue
+		uiFiles++
+		const imported = new Set()
+		for (const m of text.matchAll(IMPORT)) {
+			const from = m[2]
+			if (/^@sableui\/react(?:\/|$)/.test(from)) {
+				for (const raw of (m[1].match(/\{([^}]*)\}/)?.[1] ?? "").split(",")) {
+					const name = raw.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim()
+					if (name) imported.add(name)
+				}
+				continue
+			}
+			const lib = LIBRARIES.find(([re]) => re.test(from))?.[1] ?? (SHADCN.test(from) ? "shadcn/ui-style components/ui" : null)
+			if (lib) libraries.set(lib, (libraries.get(lib) ?? 0) + 1)
+		}
+		if (imported.size) sableFiles++
+		for (const name of imported) sableUsed.add(name)
+
+		const declared = new Map()
+		for (const re of DECLARATIONS) for (const m of text.matchAll(re)) if (!declared.has(m[1])) declared.set(m[1], m.index + m[0].indexOf(m[1]))
+		// Each component's body runs to the next declaration: close enough to
+		// tell whose markup a handler or a role belongs to.
+		const starts = [...declared.values()].sort((a, b) => a - b)
+		const own = PRIMITIVES_DIR.test(rel)
+		for (const [name, index] of declared) {
+			const hits = match(name)
+			if (!hits.length) continue
+			if (own) ownPrimitives++
+			// Built on the Sable component it is named for: a composition, not a rebuild.
+			if (hits.some((c) => imported.has(c.name))) continue
+			const behaviour = hits.some(isBehaviour)
+			const body = text.slice(index, starts.find((s) => s > index) ?? text.length)
+			if (behaviour && !HAND_BEHAVIOUR.some((re) => re.test(body))) continue
+			swaps.push({ file: rel, line: lineOf(text, index), name, sable: hits.map((c) => c.name), behaviour, ...(hits[0].partOf ? { partOf: hits[0].partOf } : {}) })
+		}
+	}
+
+	// A dependency counts even before its first import is found in these paths.
+	for (const dep of Object.keys(deps ?? {})) {
+		const lib = LIBRARIES.find(([re]) => re.test(dep))?.[1]
+		if (lib && !libraries.has(lib)) libraries.set(lib, 0)
+	}
+
+	swaps.sort((a, b) => Number(b.behaviour) - Number(a.behaviour))
+	const share = uiFiles ? sableFiles / uiFiles : 0
+	const behaviourSwaps = swaps.filter((s) => s.behaviour).length
+	const level =
+		uiFiles === 0 ? "empty"
+		: sableFiles === 0 && uiFiles <= 2 ? "fresh"
+		: sableFiles === 0 ? "none"
+		: share < 0.5 || behaviourSwaps >= 3 ? "low"
+		: "sable"
+	const foundation = libraries.size ? "library" : level === "sable" ? "sable" : ownPrimitives >= 4 ? "own" : "ad-hoc"
+
+	return {
+		informationalOnly: true,
+		level,
+		foundation,
+		uiFiles,
+		sableFiles,
+		share: +share.toFixed(2),
+		sableComponents: [...sableUsed].sort(),
+		libraries: [...libraries].map(([name, files]) => ({ name, files })),
+		swaps,
+		summary: summaryOf({ level, uiFiles, sableFiles, sableUsed, swaps }),
+		recommendation: recommendationOf({ level, foundation, libraries, behaviourSwaps }),
+	}
+}
+
+function summaryOf({ level, uiFiles, sableFiles, sableUsed, swaps }) {
+	if (level === "empty") return "No UI files yet."
+	if (level === "fresh") return `${uiFiles} UI file(s), none using Sable yet. A starter: build on Sable from here.`
+	const built = swaps.length ? `; ${swaps.length} app-built component(s) named for something Sable ships` : ""
+	return `${sableFiles} of ${uiFiles} UI files compose Sable (${sableUsed.size} distinct export${sableUsed.size === 1 ? "" : "s"})${built}.`
+}
+
+/**
+ * What the agent should do with this, in words it can relay. Never "rewrite it":
+ * the user decides whether working screens move. The foundation decides how
+ * strongly to recommend it.
+ */
+function recommendationOf({ level, foundation, libraries, behaviourSwaps }) {
+	if (level === "empty" || level === "fresh") return "Build new UI from Sable: sable search \"<need>\" before writing a component."
+	const names = [...libraries.keys()].join(", ")
+	if (level === "sable")
+		return libraries.size
+			? `Sable is the foundation, alongside ${names}. Keep new UI on Sable; offer the swaps listed when a screen is next touched.`
+			: behaviourSwaps
+				? "Sable is the foundation. Offer the few swaps listed when those screens are next touched; new UI starts with sable search."
+				: "Sable is the foundation. Keep composing from it; new UI starts with sable search."
+	if (foundation === "library")
+		return `This app also builds on ${names}. Ask the user whether Sable should replace it or only cover new work; don't mix two control libraries on one screen.`
+	if (foundation === "own")
+		return "This app has its own primitives. Offer the swaps listed, behaviour first, and keep the app's own where the user prefers them."
+	return "This app has no component foundation besides Sable. Recommend moving the listed components onto Sable, behaviour first, and ask the user before changing working screens."
+}
+
+/** One line per swap, for text output. */
+export function swapLines(report, limit = 12, indent = "      ") {
+	const lines = report.swaps.slice(0, limit).map((s) => `${indent}${s.file}:${s.line}  ${s.name} → Sable has ${s.sable.join(" or ")}${s.partOf ? ` (part of ${s.partOf})` : ""}${s.behaviour ? " (behaviour)" : ""}`)
+	if (report.swaps.length > limit) lines.push(`${indent}… ${report.swaps.length - limit} more: sable grade <paths> --json → adoption.swaps`)
+	return lines
+}

package/scripts/agent-setup.mjs

@@ -40,6 +40,27 @@ const STOP_HOOK_MARKER = "sable check --stop-hook"
 const PORTABLE = /^[\w@./ -]+$/
 const quoted = (s) => (/^[\w./-]+$/.test(s) ? s : `"${s}"`)
 
+/**
+ * How to run this project's `sable` from `root`. A workspace package is reached
+ * through the package manager's own workspace flag, since its `sable` bin is not
+ * on the root's path.
+ */
+function sableRunner({ root, project }) {
+	const projectPath = relative(resolve(root), resolve(project)).replaceAll("\\", "/")
+	const pm = packageManager(root, project)
+	if (projectPath) {
+		let name
+		try { name = JSON.parse(readFileSync(join(project, "package.json"), "utf8")).name } catch { /* unnamed */ }
+		if (typeof name === "string" && PORTABLE.test(name))
+			return {
+				pnpm: `pnpm --filter ${quoted(name)} exec sable`,
+				yarn: `yarn workspace ${quoted(name)} sable`,
+				npm: `npm exec --workspace ${quoted(name)} --no -- sable`,
+			}[pm]
+	}
+	return { pnpm: "pnpm exec sable", yarn: "yarn sable", npm: "npm exec --no -- sable" }[pm]
+}
+
 /**
  * The Claude Code Stop hook that runs `sable check` before a task can end:
  * settings.json → hooks.Stop[] → { hooks: [{ type: "command", command }] }.
@@ -51,27 +72,13 @@ const quoted = (s) => (/^[\w./-]+$/.test(s) ? s : `"${s}"`)
  * without it on Windows, PowerShell 5.1, which supports neither. `sable check
  * --stop-hook` reads CLAUDE_PROJECT_DIR from its environment instead, and
  * `--root` names the Sable package when the entries live at a repository root.
- * A workspace package is reached through the package manager's own workspace
- * flag, since its `sable` bin is not on the root's path.
+ * A workspace package is reached through sableRunner.
  */
 export function claudeStopHook({ root, project = root }) {
 	const projectPath = relative(resolve(root), resolve(project)).replaceAll("\\", "/")
 	if (projectPath.startsWith("..") || isAbsolute(projectPath)) throw new Error("--root must be the project directory or one of its ancestors, such as the repository root.")
 	if (projectPath && !PORTABLE.test(projectPath)) throw new Error(`Unsupported characters for a portable hook in the project path: ${projectPath}. Add the hook by hand.`)
-	const pm = packageManager(root, project)
-	let runner = { pnpm: "pnpm exec sable", yarn: "yarn sable", npm: "npm exec --no -- sable" }[pm]
-	if (projectPath) {
-		let name
-		try { name = JSON.parse(readFileSync(join(project, "package.json"), "utf8")).name } catch { /* unnamed */ }
-		if (typeof name === "string" && PORTABLE.test(name)) {
-			runner = {
-				pnpm: `pnpm --filter ${quoted(name)} exec sable`,
-				yarn: `yarn workspace ${quoted(name)} sable`,
-				npm: `npm exec --workspace ${quoted(name)} --no -- sable`,
-			}[pm]
-		}
-	}
-	const command = `${runner} check --stop-hook${projectPath ? ` --root ${quoted(projectPath)}` : ""}`
+	const command = `${sableRunner({ root, project })} check --stop-hook${projectPath ? ` --root ${quoted(projectPath)}` : ""}`
 	const entry = { hooks: [{ type: "command", command, timeout: 300 }] }
 	return { settingsFile: ".claude/settings.json", command, entry, settings: { hooks: { Stop: [entry] } }, installed: false }
 }
@@ -110,6 +117,63 @@ export function installClaudeStopHook({ root, project = root, dryRun = false })
 	return { ...hook, installed: true, alreadyPresent }
 }
 
+const BLOCK_BEGIN = "<!-- sable:begin"
+const BLOCK_END = "<!-- sable:end -->"
+
+/**
+ * The always-loaded half of the setup. A skill loads only when the request
+ * names it or its description matches, so "make me a pricing page" in a wired
+ * app can skip it entirely: the agent sees Tailwind and a stylesheet and writes
+ * its own Button and Modal on Sable's tokens. Project instructions (AGENTS.md
+ * for Codex and Cursor, CLAUDE.md for Claude Code) are read on every task, so a
+ * few lines there send every UI request through the skill.
+ *
+ * Short on purpose: it is in context for every task, UI or not, so it points at
+ * the skill rather than restating it.
+ */
+export function instructionsBlock({ root, project = root }) {
+	const projectPath = relative(resolve(root), resolve(project)).replaceAll("\\", "/")
+	const sable = sableRunner({ root, project })
+	const where = projectPath ? `The UI in \`${projectPath}\`` : "This app's UI"
+	return [
+		`${BLOCK_BEGIN} — managed by \`sable setup --agent\`; edit outside these markers -->`,
+		"## Sable",
+		"",
+		`${where} is built with Sable (\`@sableui/react\`). For any UI work (a page, a component, styling, layout, theming, a fix), load the \`sable\` skill first: \`/sable\` in Claude Code and Cursor, \`$sable\` in Codex. Do this even when the request does not mention Sable.`,
+		"",
+		`- Build from the installed components, utilities and tokens: \`${sable} search "<need>"\` before writing a component. Never rebuild a control Sable ships.`,
+		`- Before calling UI work done, run \`${sable} check\` and fix what fails.`,
+		"- When `check` lists app-built components that Sable already ships (Adoption), show the user that list and ask before moving working screens onto Sable.",
+		BLOCK_END,
+	].join("\n")
+}
+
+/** The managed block in `text`, as [start, end) offsets, or null. */
+function findBlock(text) {
+	const start = text.indexOf(BLOCK_BEGIN)
+	if (start === -1) return null
+	const end = text.indexOf(BLOCK_END, start)
+	if (end === -1) throw new Error("A Sable block in the project instructions has no end marker. Fix or remove it, then rerun setup.")
+	return [start, end + BLOCK_END.length]
+}
+
+/**
+ * Which project-instruction files carry the block, per host: AGENTS.md for
+ * Codex and Cursor, CLAUDE.md for Claude Code. A CLAUDE.md that already imports
+ * AGENTS.md (`@AGENTS.md`) gets the block through that import, not twice.
+ */
+function instructionFiles(root, target) {
+	const agents = target === "all" || target === "codex" || target === "cursor"
+	const claude = target === "all" || target === "claude"
+	const files = agents ? ["AGENTS.md"] : []
+	if (claude) {
+		const claudePath = join(root, "CLAUDE.md")
+		const imports = existsSync(claudePath) && /^@(?:\.\/)?AGENTS\.md\s*$/m.test(readFileSync(claudePath, "utf8"))
+		if (!(agents && imports)) files.push("CLAUDE.md")
+	}
+	return files
+}
+
 /**
  * Install discoverable loaders; the installed package owns the actual workflow.
  *
@@ -117,7 +181,7 @@ export function installClaudeStopHook({ root, project = root, dryRun = false })
  * is where the agent entries go. They differ in a monorepo, where agents start at
  * the repository root but Sable belongs to one workspace package.
  */
-export function installAgentSkill({ root, project = root, packageRoot, target = "all", update = false, dryRun = false }) {
+export function installAgentSkill({ root, project = root, packageRoot, target = "all", update = false, dryRun = false, instructions = true }) {
 	const reject = (message) => { throw new Error(message) }
 	if (!["all", "codex", "claude", "cursor"].includes(target)) reject("Choose --target all, codex, claude, or cursor.")
 	if (!existsSync(join(project, "package.json"))) reject("Run setup from a project with a package.json.")
@@ -158,14 +222,42 @@ export function installAgentSkill({ root, project = root, packageRoot, target =
 		if (current === file.content) continue
 		if (!update || receipt.files[file.path] !== hash(current)) reject(`Existing skill differs at ${file.path}. Use --update for managed files; keep or move local edits before setup.`)
 	}
+	/* The block in AGENTS.md / CLAUDE.md. Only the text between its markers is
+	 * Sable's; everything around it is the project's and is never touched. It
+	 * follows the skill files' rule: an unchanged older block refreshes under
+	 * --update, one with local edits refuses. */
+	const block = instructions ? instructionsBlock({ root, project }) : null
+	const instructionPaths = block ? instructionFiles(root, target) : []
+	const edits = []
+	for (const path of instructionPaths) {
+		checkPath(path)
+		const key = `${path}#sable`
+		const current = existsSync(join(root, path)) ? readFileSync(join(root, path), "utf8") : null
+		const eol = current?.includes("\r\n") ? "\r\n" : "\n"
+		const ours = block.replaceAll("\n", eol)
+		const found = current === null ? null : findBlock(current)
+		if (found) {
+			const existing = current.slice(...found)
+			if (existing === ours) continue
+			if (!update || receipt.files[key] !== hash(existing.replaceAll("\r\n", "\n"))) reject(`The Sable block in ${path} differs. Use --update to refresh it; keep local edits outside its markers.`)
+			edits.push({ path, key, content: current.slice(0, found[0]) + ours + current.slice(found[1]) })
+		} else if (current === null) edits.push({ path, key, content: `${block}\n` })
+		else edits.push({ path, key, content: `${current.replace(/\s*$/, "")}${eol}${eol}${ours}${eol}` })
+	}
 	if (!dryRun) {
 		for (const file of files) {
 			mkdirSync(dirname(join(root, file.path)), { recursive: true })
 			writeFileSync(join(root, file.path), file.content)
 			receipt.files[file.path] = hash(file.content)
 		}
+		for (const edit of edits) {
+			writeFileSync(join(root, edit.path), edit.content)
+			receipt.files[edit.key] = hash(block)
+		}
 		mkdirSync(dirname(join(root, receiptPath)), { recursive: true })
 		writeFileSync(join(root, receiptPath), JSON.stringify(receipt, null, 2) + "\n")
 	}
-	return { destination: destinations[0], destinations, root, project: projectPath || ".", files: files.map(file => file.path), dryRun, update, next: "Use $sable build <your brief> in Codex or /sable build <your brief> in Claude Code or Cursor." }
+	return { destination: destinations[0], destinations, root, project: projectPath || ".", files: files.map(file => file.path), instructions: instructionPaths, instructionsChanged: edits.map(edit => edit.path), dryRun, update, next: block
+		? "Ask your agent for what you want to build or change, in plain words. It uses Sable on its own; /sable (Codex: $sable) names it explicitly."
+		: "Use $sable build <your brief> in Codex or /sable build <your brief> in Claude Code or Cursor." }
 }

package/scripts/app-css.mjs

@@ -0,0 +1,129 @@
+/**
+ * app-css — what an app's own stylesheets do to Sable that its TSX does not show.
+ *
+ * The surface inventory and the part mirrors read className strings. An app that
+ * styles semantic classes in a .css file hides the rest: a work tracker passed a
+ * 100/100 grade with 48/42/34/25px bar and row heights, `.issue-table th { height:
+ * 25px; padding … }` re-laying Sable's table from outside, a disclosure chevron
+ * rotated by `[aria-expanded=false] svg`, and its light colours overridden on
+ * :root with nothing for dark — so dark mode rendered Sable's dark palette under
+ * the app's light accents, and nobody had a control to see it.
+ *
+ * Everything here is a note for the reuse inventory except `modes`, which grade
+ * reports as a warning: a half-themed palette is a defect a user sees the moment
+ * they switch modes, while a fixed height or a reached-in selector can be a
+ * deliberate choice. Lexical, like the rest of grade; it parses enough CSS to
+ * know each declaration's selector and the @-rules around it.
+ */
+
+/** Every declaration block with its selector and enclosing @-rule preludes. */
+export function cssRules(css) {
+	const src = css.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+	const rules = []
+	const stack = []
+	let start = 0
+	let quote = null
+	for (let i = 0; i < src.length; i++) {
+		const c = src[i]
+		if (quote) {
+			if (c === "\\") i++
+			else if (c === quote) quote = null
+			continue
+		}
+		if (c === '"' || c === "'") quote = c
+		else if (c === "{") {
+			const prelude = src.slice(start, i).split(";").at(-1).trim()
+			stack.push({ prelude, index: start + src.slice(start, i).lastIndexOf(prelude), body: i + 1 })
+			start = i + 1
+		} else if (c === "}") {
+			const top = stack.pop()
+			if (top && !top.prelude.startsWith("@")) {
+				const body = src.slice(start, i)
+				const context = stack.map((s) => s.prelude)
+				// Nested rules: `.a { .b { … } }` — the declarations are the block's own text.
+				rules.push({ selector: top.prelude, context, body, index: top.index, bodyIndex: top.body })
+			}
+			start = i + 1
+		}
+	}
+	return rules
+}
+
+const declarations = (body) =>
+	[...body.matchAll(/(?:^|;|\})\s*(--[\w-]+|[a-z-]+)\s*:\s*([^;{}]+)/g)].map((m) => ({ prop: m[1], value: m[2].trim(), offset: m.index + m[0].indexOf(m[1]) }))
+
+const lineOf = (text, index) => text.slice(0, index).split("\n").length
+
+/** A selector's last compound names a bar, a row, a header or a table cell. */
+const BAR_OR_ROW = /(?:^|[\s>+~])(?:th|td|tr|thead|header)(?![\w-])|\.[\w-]*(?:bar|row|header|cell|tab|toolbar|item)(?![\w-])/
+/** The density ladder's own names, re-declared by hand. */
+const LADDER = /^--(?:control-(?:xs|sm|md|lg|cta)|chrome-bar-height|status-bar-height)$/
+
+/**
+ * Notes on one stylesheet. `semantic` is the theme contract's colour token
+ * names, used by `modes` across all of an app's stylesheets, not here.
+ */
+export function cssNotes(css) {
+	const notes = []
+	const seen = new Set()
+	const add = (index, kind, what, consider) => {
+		const key = `${kind}|${what}`
+		if (seen.has(key)) return
+		seen.add(key)
+		notes.push({ line: lineOf(css, index), kind, what, consider })
+	}
+	for (const r of cssRules(css)) {
+		const decls = declarations(r.body)
+		const at = (d) => r.bodyIndex + d.offset
+		if (/\[(?:aria-expanded|data-panel-open|data-open|data-state)[^\]]*\][^{,]*\bsvg\b/.test(r.selector) && decls.some((d) => /^(?:transform|rotate)$/.test(d.prop) && /rotate/.test(`${d.prop} ${d.value}`))) {
+			add(r.index, "rebuilt part", `${r.selector} rotates a disclosure chevron by hand`, "CollapsibleIndicator, which flips with the panel and eases (Accordion, Select and Menu triggers already flip theirs)")
+		}
+		if (/(?:^|[\s>+~])(?:th|td|thead|tr)(?![\w-])/.test(r.selector) && /^[.#[]/.test(r.selector.trim())) {
+			const props = decls.filter((d) => /^(?:height|min-height|padding|padding-block|padding-inline|font-size|font-weight)$/.test(d.prop))
+			if (props.length) add(r.index, "override", `${r.selector} { ${props.map((d) => d.prop).join(", ")} } re-lays a Sable table from outside`, "the table's density (rows follow a Workspace or Density scope), a column's className for its width, CardContent flush for edge padding")
+		}
+		if (/\[data-(?:selected|highlighted|active|checked|pressed)\]/.test(r.selector) && /^[.#]/.test(r.selector.trim())) {
+			add(r.index, "override", `${r.selector} restyles a Sable state from outside`, "the state's own tokens set on the theme (--muted for a selected row), or the component's variant")
+		}
+		for (const d of decls) {
+			const px = /^(\d+(?:\.\d+)?)px$/.exec(d.value)?.[1]
+			if (/^(?:height|min-height)$/.test(d.prop) && px && Number(px) >= 16 && Number(px) <= 64 && BAR_OR_ROW.test(r.selector)) {
+				add(at(d), "fixed height", `${r.selector} { ${d.prop}: ${d.value} }`, "the density ladder: --chrome-bar-height, --status-bar-height or --control-* follow the register (WorkspaceBar, StatusBar, a Density scope) instead of pinning one size")
+			}
+		}
+		const ladder = decls.filter((d) => LADDER.test(d.prop) && /^\d/.test(d.value))
+		if (ladder.length) {
+			const where = [...r.context.filter((c) => c.startsWith("@media")), r.selector].join(" ")
+			add(at(ladder[0]), "fixed height", `${where} { ${ladder.map((d) => `${d.prop}: ${d.value}`).join("; ")} } re-declares the density ladder`, "Workspace's density prop or <Density value=…>; the compact and comfortable ladders are already measured")
+		}
+	}
+	return notes
+}
+
+/** The selectors and @-rules that put a declaration in the dark mode. */
+const DARK = /\.dark\b|\[data-(?:mode|theme|color-scheme)=["']?dark|prefers-color-scheme:\s*dark|:root\.dark|html\.dark|\[data-dark\]/
+
+/**
+ * Light and dark coverage of the theme's colour tokens across every stylesheet.
+ * Returns the tokens an app sets only for light, and whether it set any dark
+ * values at all. A preset carries both modes; hand-written :root overrides
+ * usually carry one.
+ */
+export function modeCoverage(sheets, semantic) {
+	const light = new Map()
+	const dark = new Set()
+	for (const { rel, text } of sheets) {
+		for (const r of cssRules(text)) {
+			const scope = [...r.context, r.selector].join(" ")
+			const isDark = DARK.test(scope)
+			for (const d of declarations(r.body)) {
+				const name = d.prop.slice(2)
+				if (!d.prop.startsWith("--") || !semantic.has(name)) continue
+				if (isDark) dark.add(name)
+				else if (!light.has(name)) light.set(name, { file: rel, line: lineOf(text, r.index) })
+			}
+		}
+	}
+	const lightOnly = [...light].filter(([name]) => !dark.has(name)).map(([name, at]) => ({ name, ...at }))
+	return { light: light.size, dark: dark.size, lightOnly }
+}