cascivo 0.3.6 → 0.4.1

package/dist/index.mjs

@@ -200,14 +200,14 @@ function resolveTemplateTarget(cwd, target) {
 }
 /**
 * Names from other libraries → the cascivo layout primitive that fills the same
-* role, so `cascivo add flex` installs `layout/stack`. Bare names that already
-* resolve (e.g. `stack` → `layout/stack` via suffix match) need no alias.
+* role, so `cascivo add box` installs `layout/flex`. Bare names that already
+* resolve (e.g. `flex` → `layout/flex` via suffix match) still list an alias here
+* for discoverability.
 */
 const LAYOUT_ALIASES = {
-	flex: "stack",
-	box: "stack",
-	hstack: "stack",
-	vstack: "stack",
+	box: "layout/flex",
+	hstack: "layout/flex",
+	vstack: "layout/flex",
 	gap: "spacer"
 };
 /**
@@ -526,7 +526,9 @@ function indexHtml(opts) {
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>${opts.name}</title>
     <style>
-      @layer cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component, cascivo.theme, cascivo.override;
+      @layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component, cascivo.theme, cascivo.blocks, cascivo.override;
+      /* Third-party CSS goes in the low-priority vendor layer so it can't beat cascivo:
+         @import url('some-lib/styles.css') layer(vendor); — see docs/THIRD-PARTY-CSS.md */
       @layer cascivo.reset {
         *,
         *::before,
@@ -687,6 +689,54 @@ npm run dev
 Add more components with \`npx cascivo add <component>\`.
 `;
 }
+function agentsMd(opts) {
+	return `# Agent instructions — ${opts.name}
+
+This is a [cascivo](https://cascivo.com) app. When generating or editing CSS, follow
+the **layer contract** — cascivo styles live in cascade layers, and layer order beats
+selector specificity.
+
+## CSS layer contract
+
+1. Every declaration goes inside an \`@layer\` block. Unlayered CSS beats all layers
+   regardless of specificity — never emit it.
+2. Never invent layer names. Write only: your app slot \`cascivo.example\` (declared in
+   the order statement in \`index.html\`) for page styles, and
+   \`@layer cascivo.override { … }\` for hotfixes / one-off overrides — it beats
+   everything cascivo ships.
+3. Never nest layers deeper than the shipped \`cascivo.blocks.<name>\` pattern. For
+   sub-elements, use native CSS nesting inside one layer block, not new sublayers.
+4. Third-party CSS: \`@import url('lib/styles.css') layer(vendor);\` with \`vendor\`
+   declared before the cascivo layers. Don't import vendor CSS from JavaScript — route it
+   through a CSS file, or use \`@cascivo/vite-plugin\` (\`cascivoLayers\`) to layer it.
+5. Style with \`--cascivo-*\` tokens, not raw values.
+
+This app's declared layer order (in \`index.html\`):
+
+\`\`\`css
+@layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component,
+  cascivo.theme, cascivo.blocks, cascivo.override;
+\`\`\`
+
+### Worked example — nesting, not new layers
+
+\`\`\`css
+@layer cascivo.override {
+  .projectCard {
+    /* Sub-elements nest inside the one block — no cascivo.card.status sublayer. */
+    .statusBadge {
+      color: var(--cascivo-color-text-subtle);
+      .pulseDot {
+        background: var(--cascivo-color-success);
+      }
+    }
+  }
+}
+\`\`\`
+
+More: cascivo's machine-readable guide is at https://cascivo.com/llms.txt.
+`;
+}
 /** Build the full set of files for a new cascivo app. Pure — no filesystem I/O. */
 function buildScaffold(opts) {
 	const sections = resolveSections(opts.sections);
@@ -719,6 +769,10 @@ function buildScaffold(opts) {
 			path: "README.md",
 			contents: readme(opts)
 		},
+		{
+			path: "AGENTS.md",
+			contents: agentsMd(opts)
+		},
 		{
 			path: "src/main.tsx",
 			contents: mainTsx()
@@ -888,6 +942,10 @@ async function runDoctor(root) {
 function isTranslationRef(v) {
 	return typeof v === "object" && v !== null && "$t" in v;
 }
+/** A JS literal for a state initial value. */
+function serializeInitial(value) {
+	return typeof value === "string" ? `'${value.replace(/'/g, "\\'")}'` : String(value);
+}
 function serializeProp(value) {
 	if (typeof value === "string") return `"${value.replace(/"/g, "\\\"")}"`;
 	if (typeof value === "number" || typeof value === "boolean") return `{${value}}`;
@@ -907,14 +965,15 @@ function renderNode(node, indent, _parentPropNames, knownComponents) {
 	knownComponents.add(compName);
 	const propParts = [];
 	if (node.props) for (const [k, v] of Object.entries(node.props)) propParts.push(`${k}=${serializeProp(v)}`);
-	if (node.bind) for (const [k, ref] of Object.entries(node.bind)) {
-		const path = ref.replace(/^\$data\./, "").replace(/\./g, ".");
-		propParts.push(`${k}={data.${path}}`);
-	}
-	if (node.events) for (const [k, ref] of Object.entries(node.events)) {
-		const actionName = ref.replace(/^\$actions\./, "");
-		propParts.push(`${k}={actions.${actionName}}`);
-	}
+	if (node.bind) for (const [k, ref] of Object.entries(node.bind)) if (ref.startsWith("$state.")) propParts.push(`${k}={${ref.slice(7)}.value}`);
+	else propParts.push(`${k}={data.${ref.replace(/^\$data\./, "")}}`);
+	if (node.events) for (const [k, ref] of Object.entries(node.events)) if (ref.startsWith("$state.set.")) {
+		const key = ref.slice(11);
+		propParts.push(`${k}={(e) => (${key}.value = coerceValue(e))}`);
+	} else if (ref.startsWith("$state.toggle.")) {
+		const key = ref.slice(14);
+		propParts.push(`${k}={() => (${key}.value = !${key}.value)}`);
+	} else propParts.push(`${k}={actions.${ref.replace(/^\$actions\./, "")}}`);
 	const propsStr = propParts.length > 0 ? " " + propParts.join(" ") : "";
 	const childrenStr = node.children !== void 0 ? renderChildren(node.children, indent, [], knownComponents) : void 0;
 	if (childrenStr !== void 0 && childrenStr !== "") return `${indent}<${compName}${propsStr}>\n${indent}  ${childrenStr}\n${indent}</${compName}>`;
@@ -925,10 +984,12 @@ function collectBindAndEvents(nodes) {
 	const actionProps = [];
 	function walk(node) {
 		if (node.bind) for (const ref of Object.values(node.bind)) {
+			if (ref.startsWith("$state.")) continue;
 			const path = ref.replace(/^\$data\./, "");
 			if (!boundProps.includes(path)) boundProps.push(path);
 		}
 		if (node.events) for (const ref of Object.values(node.events)) {
+			if (ref.startsWith("$state.")) continue;
 			const name = ref.replace(/^\$actions\./, "");
 			if (!actionProps.includes(name)) actionProps.push(name);
 		}
@@ -940,9 +1001,21 @@ function collectBindAndEvents(nodes) {
 		actionProps
 	};
 }
+/** True if any node writes state via "$state.set.*" (needs the coerceValue helper). */
+function usesStateSetter(nodes) {
+	const walk = (node) => {
+		if (node.events && Object.values(node.events).some((r) => r.startsWith("$state.set."))) return true;
+		return Array.isArray(node.children) ? node.children.some(walk) : false;
+	};
+	return nodes.some(walk);
+}
 function generateTsx(config, _propMetas, componentsPath) {
 	const knownComponents = /* @__PURE__ */ new Set();
-	const { boundProps, actionProps } = collectBindAndEvents(Object.values(config.view.regions).flat());
+	const allNodes = Object.values(config.view.regions).flat();
+	const { boundProps, actionProps } = collectBindAndEvents(allNodes);
+	const stateEntries = Object.entries(config.state ?? {});
+	const hasState = stateEntries.length > 0;
+	const needsCoerce = usesStateSetter(allNodes);
 	const regionBlocks = Object.entries(config.view.regions).map(([regionName, nodes]) => {
 		return `    <div className="region-${regionName}">\n${nodes.map((n) => renderNode(n, "      ", [], knownComponents)).join("\n")}\n    </div>`;
 	}).join("\n");
@@ -950,13 +1023,24 @@ function generateTsx(config, _propMetas, componentsPath) {
 	const hasData = boundProps.length > 0;
 	const hasActions = actionProps.length > 0;
 	const params = [hasData ? `data: {\n${boundProps.map((p) => `    ${p.replace(/\./g, "_")}: unknown // TODO: type your data`).join("\n")}\n  }` : "", hasActions ? `actions: {\n${actionProps.map((a) => `    ${a}: (...args: unknown[]) => unknown`).join("\n")}\n  }` : ""].filter(Boolean).join(",\n  ");
-	return `import React from 'react'
+	const propsType = params ? `{\n  ${params}\n}` : "{}";
+	const coreImport = hasState ? "\nimport { useSignal, useSignals } from '@cascivo/core'" : "";
+	const coerceHelper = needsCoerce ? `
+/** Unwrap a DOM event into the value a state setter should store. */
+function coerceValue(e: unknown) {
+  const t = (e as { target?: { type?: string; checked?: boolean; value?: unknown } })?.target
+  if (t) return t.type === 'checkbox' || t.type === 'radio' ? t.checked : t.value
+  return e
+}
+` : "";
+	const stateDecls = hasState ? "  useSignals()\n" + stateEntries.map(([k, v]) => `  const ${k} = useSignal(${serializeInitial(v)})`).join("\n") + "\n" : "";
+	return `import React from 'react'${coreImport}
 ${importLines}
-
-interface PageProps ${params ? `{\n  ${params}\n}` : "{}"}
+${coerceHelper}
+interface PageProps ${propsType}
 
 export function GeneratedPage({ ${hasData ? "data, " : ""}${hasActions ? "actions" : ""} }: PageProps) {
-  return (
+${stateDecls}  return (
     <div className="cascade-view">
 ${regionBlocks}
     </div>
@@ -1112,7 +1196,7 @@ async function list(config, options = {}) {
 		return existsSync(join(process.cwd(), config.outputDir, outputName));
 	});
 	console.log(formatList(components));
-	console.log("\nTip: install any entry by its bare name — `cascivo add stack` resolves to `layout/stack`. Layout primitives (Stack, Grid, AutoGrid, Columns, Spacer, Center) replace inline-style layout; see docs/cookbooks/layout-and-spacing.md.");
+	console.log("\nTip: install any entry by its bare name — `cascivo add flex` resolves to `layout/flex`. Layout primitives (Flex, Grid, AutoGrid, Columns, Spacer, Center) replace inline-style layout; see docs/cookbooks/layout-and-spacing.md.");
 }
 //#endregion
 //#region src/commands/registry.ts
@@ -2131,7 +2215,7 @@ async function run(args) {
 			break;
 		}
 		case "audit": {
-			const { audit } = await import("./audit-InQqdY1s.mjs");
+			const { audit } = await import("./audit-g0Ac-Uzl.mjs");
 			await audit(rest, await loadConfig());
 			break;
 		}