@homepages/create-workspace 0.9.0 → 0.10.1

package/dist/index.js

@@ -2,7 +2,7 @@
 // `npm create @homepages/workspace <name>` — stamp a workspace container: shared
 // root context + one working starter template, then install and git-init.
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -10,6 +10,14 @@ import { fileURLToPath } from "node:url";
 import { stampTree } from "./stamp.js";
 const ASSETS = join(dirname(fileURLToPath(import.meta.url)), "..", "scaffold");
 const NAME_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * The kit's caret pin. The kit versions independently of this scaffolder, so
+ * it cannot be derived from this package's own version and is a committed
+ * constant — same reasoning as ESLINT_PLUGIN_VERSION below — bumped when the
+ * kit releases a new minor. A scaffolded workspace pinned to a stale range
+ * never picks up the kit's current contract.
+ */
+const KIT_VERSION = "0.10.0";
 /**
  * The authoring ESLint preset's caret pin. Unlike the kit it cannot be derived from
  * this package's own version — @homepages/eslint-plugin-template versions
@@ -17,7 +25,7 @@ const NAME_RE = /^[a-z][a-z0-9-]*$/;
  * new minor. A scaffolded workspace whose config imports a preset it does not depend
  * on fails at `npm install`, not at lint time, so this is not optional.
  */
-const ESLINT_PLUGIN_VERSION = "0.1.0";
+const ESLINT_PLUGIN_VERSION = "0.2.0";
 /**
  * The CLI's caret pin. Same reasoning as ESLINT_PLUGIN_VERSION: @homepages/template-cli
  * versions independently of the kit, so it cannot be derived from this package's own
@@ -27,14 +35,34 @@ const ESLINT_PLUGIN_VERSION = "0.1.0";
  * kit no longer carries a bin — so a workspace missing it fails on `npm run dev` with
  * "command not found", which reads as a broken scaffold rather than a missing pin.
  */
-const TEMPLATE_CLI_VERSION = "0.1.0";
+const TEMPLATE_CLI_VERSION = "0.2.0";
+/**
+ * The dev media pack's caret pin. Same committed-constant reasoning as the pins
+ * above — the pack versions independently of this scaffolder.
+ *
+ * The pack is what the `dev` server serves asset BYTES from: the kit carries only
+ * the manifest (copied into its dist at build time), so a workspace without this
+ * dependency has an index of media it cannot resolve a single pixel of, and every
+ * fixture image renders broken.
+ *
+ * It is a devDependency, not a dependency: media is dev-time authoring content, in
+ * the same category as vite and the rest of the toolchain, and nothing in a packed
+ * template references it.
+ *
+ * This range must cover the pack's actual published version on npm, or a
+ * scaffolded workspace outside this monorepo dies on `npm install` with a 404 —
+ * the drift guard in `src/index.test.ts` (the stamped dev-media range covers the
+ * pack's actual version) fails the moment this constant falls behind a real bump.
+ */
+const DEV_MEDIA_VERSION = "0.0.1";
 export async function scaffoldWorkspace(name, targetDir, opts) {
     await mkdir(targetDir, { recursive: true });
     await stampTree(join(ASSETS, "workspace"), targetDir, {
         WORKSPACE_NAME: name,
-        KIT_VERSION: opts.kitVersion,
+        KIT_VERSION: opts.kitVersion ?? KIT_VERSION,
         ESLINT_PLUGIN_VERSION: opts.eslintPluginVersion ?? ESLINT_PLUGIN_VERSION,
         TEMPLATE_CLI_VERSION: opts.templateCliVersion ?? TEMPLATE_CLI_VERSION,
+        DEV_MEDIA_VERSION: opts.devMediaVersion ?? DEV_MEDIA_VERSION,
     });
     await stampTree(join(ASSETS, "template"), join(targetDir, "templates", "starter"), {
         TEMPLATE_KEY: "starter",
@@ -45,17 +73,6 @@ export async function scaffoldWorkspace(name, targetDir, opts) {
     if (opts.install !== false)
         execFileSync("npm", ["install"], { cwd: targetDir, stdio: "inherit" });
 }
-/**
- * The kit version to caret-pin: this scaffolder is published version-synced
- * with the kit, so its own `version` IS the kit version. Read at runtime
- * (rather than a static JSON import) because `../package.json` sits outside
- * `rootDir: "src"` and trips TS6059 under a static import.
- */
-function kitVersion() {
-    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
-    const pkg = JSON.parse(raw);
-    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
-}
 async function promptName() {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -77,7 +94,7 @@ async function main() {
         process.stderr.write(`create-workspace: ${name}/ already exists.\n`);
         return 1;
     }
-    await scaffoldWorkspace(name, targetDir, { kitVersion: kitVersion() });
+    await scaffoldWorkspace(name, targetDir, {});
     process.stdout.write(`\nCreated ${name}/\n\n` +
         `  cd ${name}\n` +
         `  npm run dev        # preview the starter (the island hydrates)\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homepages/create-workspace",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Scaffold a HomePages template workspace.",
   "license": "UNLICENSED",
   "type": "module",

package/scaffold/section/_Renderer.tsx

@@ -1,19 +1,21 @@
 import type { ReactNode } from "react";
 
-import { Section, Slot } from "@homepages/template-kit";
+import { Section, slotMarkers } from "@homepages/template-kit";
 
-import type { Props } from "./schema";
+import type { Props, schema } from "./schema";
 
-// {{SECTION_DISPLAY}} — a pure, server-rendered function of its props. Wrap
-// every editable slot in <Slot id="…"> so the editor can resolve clicks. For
-// interactivity, add a "use client" island file beside this one.
+const { slot } = slotMarkers<typeof schema>();
+
+// {{SECTION_DISPLAY}} — a pure, server-rendered function of its props. `slots.x` is your
+// data; `{...slot.x}` tells the editor where you put it. For interactivity, add a
+// "use client" island file beside this one.
 export default function {{SECTION_PASCAL}}Renderer({ slots, nav }: Props): ReactNode {
   return (
     <Section id={nav.selfAnchor} className="bg-background text-ink">
       <div className="mx-auto max-w-3xl px-6 py-12">
-        <Slot id="headline" textLeaf>
-          <h2 className="text-2xl font-semibold">{slots.headline}</h2>
-        </Slot>
+        <h2 className="text-2xl font-semibold" {...slot.headline.text}>
+          {slots.headline}
+        </h2>
       </div>
     </Section>
   );

package/scaffold/template/_manifest.json

@@ -3,7 +3,7 @@
   "name": "{{TEMPLATE_NAME}}",
   "deliverable_type": "single_property_website",
   "sections": [
-    { "section": "hero", "instance_id": "hero-1", "options": {}, "locked": [], "required": true, "reorderable": false }
+    { "section": "hero", "instance_id": "hero-1", "options": {}, "locked": [], "required": true }
   ],
   "reconcile": []
 }

package/scaffold/template/sections/hero/Renderer.tsx

@@ -1,35 +1,35 @@
 import type { ReactNode } from "react";
 
-import { Image, Section, Slot } from "@homepages/template-kit";
+import { Image, Section, slotMarkers } from "@homepages/template-kit";
 
 import { Feature } from "./components/Feature";
 import ExpandableText from "./ExpandableText";
-import type { Props } from "./schema";
+import type { Props, schema } from "./schema";
 
-// Hero — a pure server-rendered function of its props: no fetches, no globals,
-// no state. Every editable slot's outer DOM is wrapped in <Slot id="…"> (or a
-// primitive with slotId="…") so the editor can map a click back to the slot.
-// The one interactive part is the <ExpandableText> island.
+const { slot } = slotMarkers<typeof schema>();
+
+// Hero — a pure server-rendered function of its props: no fetches, no globals, no state.
+// `slots.x` is your data; `{...slot.x}` tells the editor where you put it. The one
+// interactive part is the <ExpandableText> island.
 export default function HeroRenderer({ slots, options, nav }: Props): ReactNode {
   const align = options.align === "left" ? "items-start text-left" : "items-center text-center";
   return (
     <Section id={nav.selfAnchor} className="bg-background text-ink">
       <Image
-        slotId="hero_image"
-        src={slots.hero_image.url}
-        responsive={slots.hero_image.responsive}
-        alt={slots.hero_image.alt}
+        {...slot.hero_image}
+        value={slots.hero_image}
+        frame={false}
         loading="eager"
         className="w-full"
       />
       <div className={`mx-auto flex max-w-3xl flex-col gap-4 px-6 py-12 ${align}`}>
-        <Slot id="headline" textLeaf>
-          <h1 className="text-3xl font-semibold">{slots.headline}</h1>
-        </Slot>
-        <Slot id="blurb">
+        <h1 className="text-3xl font-semibold" {...slot.headline.text}>
+          {slots.headline}
+        </h1>
+        <div {...slot.blurb}>
           {/* The island receives JSON-serializable props only. */}
           <ExpandableText text={slots.blurb} collapsedChars={140} moreLabel="Read more" />
-        </Slot>
+        </div>
         <div className="mt-2 grid w-full grid-cols-2 gap-3">
           <Feature label="Status" value="For sale" />
           <Feature label="Type" value="Single-family" />

package/scaffold/template/sections/hero/fixtures.ts

@@ -6,7 +6,7 @@ import { luxuryMultiUnit } from "@homepages/template-kit/fixtures";
 // needed for it. Add a `states` entry only for a designed scenario that
 // combines overrides at once (a content-length or option branch the section
 // renders differently).
-const heroImage = luxuryMultiUnit.photos[19]!; // exterior facade shot
+const heroImage = luxuryMultiUnit.photos.find((p) => p.tags.room === "exterior-front")!;
 
 const fixtures: FixtureModule = {
   base: {

package/scaffold/workspace/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Tool-agnostic mirror of CLAUDE.md — keep the two in sync. -->
-
+<!-- BEGIN:homepages-kit -->
 # {{WORKSPACE_NAME}} — agent guide
 
 You are authoring HomePages marketing-section templates in this workspace.
@@ -15,8 +15,13 @@ You are authoring HomePages marketing-section templates in this workspace.
   All three are declared once, at this root, and every template shares them. Do not
   add per-template `package.json`, `tsconfig`, or `eslint` files — there is exactly
   one of each, at this root.
-- **The docs corpus is your whole universe:** `node_modules/@homepages/template-kit/guide/`
-  (`llms.txt` is the router). Read it before authoring; do not guess the contract.
+- **Read the docs corpus before authoring — your training data is outdated.** The
+  authoring contract changes with every kit minor, and the corpus installed in this
+  workspace is the version you are building against:
+  `node_modules/@homepages/template-kit/guide/` (`llms.txt` is the router). Grep it;
+  do not guess the contract, and do not rely on what you remember about it. The same
+  pages are browsable at https://docs.homepages.io, but the local copy is
+  authoritative — it matches your installed version.
 
 ## The section contract (reserved files)
 
@@ -46,3 +51,7 @@ islands — is yours to organize.
 
 Read the starter section (`templates/starter/sections/hero/`) — it is a working,
 annotated example of the whole contract.
+<!-- END:homepages-kit -->
+
+<!-- Your own notes belong outside the markers above; anything inside them may be
+     replaced when the kit updates this file. -->

package/scaffold/workspace/CLAUDE.md

@@ -1,3 +1,4 @@
+<!-- BEGIN:homepages-kit -->
 # {{WORKSPACE_NAME}} — agent guide
 
 You are authoring HomePages marketing-section templates in this workspace.
@@ -13,8 +14,13 @@ You are authoring HomePages marketing-section templates in this workspace.
   All three are declared once, at this root, and every template shares them. Do not
   add per-template `package.json`, `tsconfig`, or `eslint` files — there is exactly
   one of each, at this root.
-- **The docs corpus is your whole universe:** `node_modules/@homepages/template-kit/guide/`
-  (`llms.txt` is the router). Read it before authoring; do not guess the contract.
+- **Read the docs corpus before authoring — your training data is outdated.** The
+  authoring contract changes with every kit minor, and the corpus installed in this
+  workspace is the version you are building against:
+  `node_modules/@homepages/template-kit/guide/` (`llms.txt` is the router). Grep it;
+  do not guess the contract, and do not rely on what you remember about it. The same
+  pages are browsable at https://docs.homepages.io, but the local copy is
+  authoritative — it matches your installed version.
 
 ## The section contract (reserved files)
 
@@ -44,3 +50,7 @@ islands — is yours to organize.
 
 Read the starter section (`templates/starter/sections/hero/`) — it is a working,
 annotated example of the whole contract.
+<!-- END:homepages-kit -->
+
+<!-- Your own notes belong outside the markers above; anything inside them may be
+     replaced when the kit updates this file. -->

package/scaffold/workspace/_package.json

@@ -13,6 +13,7 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@homepages/dev-media": "^{{DEV_MEDIA_VERSION}}",
     "@homepages/eslint-plugin-template": "^{{ESLINT_PLUGIN_VERSION}}",
     "@homepages/template-cli": "^{{TEMPLATE_CLI_VERSION}}",
     "@tailwindcss/cli": "^4.3.0",