@jxsuite/starters 1.7.0 → 1.8.0

package/README.md

@@ -1,14 +1,8 @@
 # @jxsuite/starters
 
-The catalogue of ready-made **starter sites** a user can clone when creating a
-new Jx project, either from Studio's New Project picker or with
-`bun create @jxsuite <directory> --template <id>`. The package is two things:
-`registry.json`, the picker metadata, and `sites/`, one complete buildable Jx
-project tree per starter.
+The catalogue of ready-made **starter sites** a user can clone when creating a new Jx project, either from Studio's New Project picker or with `bun create @jxsuite <directory> --template <id>`. The package is two things: `registry.json`, the picker metadata, and `sites/`, one complete buildable Jx project tree per starter.
 
-The TypeScript module itself is metadata-only. It reads the registry and
-resolves a starter's directory; the copy-and-rewrite of a clone happens in
-[`@jxsuite/create`](../create/README.md)'s `generate.ts`.
+The TypeScript module itself is metadata-only. It reads the registry and resolves a starter's directory; the copy-and-rewrite of a clone happens in [`@jxsuite/create`](../create/README.md)'s `generate.ts`.
 
 ## API
 
@@ -20,18 +14,11 @@ getStarter("restaurant"); // StarterMeta | undefined
 getStarterDir("restaurant"); // <SITES_DIR>/restaurant; throws on an unknown id
 ```
 
-`SITES_DIR` is `join(import.meta.dirname, "sites")`, so the same code resolves
-from the monorepo and from the copy staged inside the packaged desktop app.
-`getStarterDir` throws `Unknown starter: "<id>"` rather than handing back a path
-that does not exist. The registry is also exported raw as
-`@jxsuite/starters/registry.json`, for consumers that want the array without the
-module. The package publishes raw TypeScript: `exports["."]` is `./index.ts`,
-there is no build step, and the module imports only `node:fs` and `node:path`.
+`SITES_DIR` is `join(import.meta.dirname, "sites")`, so the same code resolves from the monorepo and from the copy staged inside the packaged desktop app. `getStarterDir` throws `Unknown starter: "<id>"` rather than handing back a path that does not exist. The registry is also exported raw as `@jxsuite/starters/registry.json`, for consumers that want the array without the module. The package publishes raw TypeScript: `exports["."]` is `./index.ts`, there is no build step, and the module imports only `node:fs` and `node:path`.
 
 ## The registry contract
 
-`registry.json` is a flat JSON array. Every entry carries all eight fields;
-there are no optional keys and no defaults (`index.ts`, `StarterMeta`):
+`registry.json` is a flat JSON array. Every entry carries all eight fields; there are no optional keys and no defaults (`index.ts`, `StarterMeta`):
 
 | Field         | Contract                                                     |
 | ------------- | ------------------------------------------------------------ |
@@ -44,24 +31,13 @@ there are no optional keys and no defaults (`index.ts`, `StarterMeta`):
 | `accent`      | Hex colour, `/^#[0-9a-fA-F]{3,8}$/`                          |
 | `thumbnail`   | `data:image/…` URI (**generated**, see below)                |
 
-`tests/registry.test.ts` asserts each of those, that ids are unique, and that
-every id maps to a `sites/<id>/project.json`. Never restate the number of
-starters in prose: `scripts/docs/check-site-claims.ts` reads `registry.json` and
-fails the root `README.md` or any `sites/jxsuite.com/pages/**` page claiming a
-different count (digits and number words alike). The same gate holds the
-templates page's `::starter-card` slugs to the registry ids, both directions, so
-a starter added without a card is caught too. It does not scan this file, so
-here the habit is the only guard.
+`tests/registry.test.ts` asserts each of those, that ids are unique, and that every id maps to a `sites/<id>/project.json`. Never restate the number of starters in prose: `scripts/docs/check-site-claims.ts` reads `registry.json` and fails the root `README.md` or any `sites/jxsuite.com/pages/**` page claiming a different count (digits and number words alike). The same gate holds the templates page's `::starter-card` slugs to the registry ids, both directions, so a starter added without a card is caught too. It does not scan this file, so here the habit is the only guard.
 
-The registry is the source several unrelated gates read by path: the docs
-generator, the marketing-claims count check, the packaged-desktop bundle
-verifier, and the screenshot lane's shot selector.
+The registry is the source several unrelated gates read by path: the docs generator, the marketing-claims count check, the packaged-desktop bundle verifier, and the screenshot lane's shot selector.
 
 ## Layout of `sites/`
 
-Each `sites/<id>/` is a complete, buildable Jx project. It contains
-`components/`, `layouts/`, `pages/`, `content/`, `public/`, `project.json`, a
-`package.json`, and two **committed generated** entry schemas:
+Each `sites/<id>/` is a complete, buildable Jx project. It contains `components/`, `layouts/`, `pages/`, `content/`, `public/`, `project.json`, a `package.json`, and two **committed generated** entry schemas:
 
 ```
 sites/restaurant/
@@ -74,123 +50,55 @@ sites/restaurant/
   .gitignore             # .cache, dist, node_modules
 ```
 
-`tests/validate.test.ts` holds the tree to its schemas: the two committed
-bundles must be self-contained (no relative `$ref`s survive), `project.json`
-must satisfy both `parseProjectConfig` and its own `project.schema.json`, every
-`{components,layouts,pages}/**/*.json` must validate against
-`document.schema.json` (and at least one must exist), and every
-`content/**/*.md` must start with frontmatter. `tests/validate-projects.test.ts`
-runs each starter through `@jxsuite/schema`'s `validateProjectFile` as well.
+`tests/validate.test.ts` holds the tree to its schemas: the two committed bundles must be self-contained (no relative `$ref`s survive), `project.json` must satisfy both `parseProjectConfig` and its own `project.schema.json`, every `{components,layouts,pages}/**/*.json` must validate against `document.schema.json` (and at least one must exist), and every `content/**/*.md` must start with frontmatter. `tests/validate-projects.test.ts` runs each starter through `@jxsuite/schema`'s `validateProjectFile` as well.
 
-Starters are not uniform by design: the museum starter is the multilingual one
-(`i18n.locales: ["en", "fr-CA", "ar"]` with `routing: "prefix-except-default"`),
-and real-estate's `listings` collection uses `format: "Csv"` where the others
-use Markdown.
+Starters are not uniform by design: the museum starter is the multilingual one (`i18n.locales: ["en", "fr-CA", "ar"]` with `routing: "prefix-except-default"`), and real-estate's `listings` collection uses `format: "Csv"` where the others use Markdown.
 
 ## Consumption: cloned, never depended on
 
-Nothing a user ships depends on this package. `@jxsuite/create` imports
-`getStarterDir` lazily (so blank projects never load the large starters
-package), copies the tree, and then re-stamps identity:
+Nothing a user ships depends on this package. `@jxsuite/create` imports `getStarterDir` lazily (so blank projects never load the large starters package), copies the tree, and then re-stamps identity:
 
 ```sh
 bun create @jxsuite my-site --template restaurant
 ```
 
-- **Excluded from the copy**: `node_modules`, `dist`, `.cache`, `.jx-cache`,
-  `.git`, and `images.json` (`packages/create/generate.ts`).
-- **`project.json` is preserved**, with only `name` / `url` / `description` /
-  `build.adapter` re-stamped (plus design tokens when the quickstart supplies
-  them). Content, components, layouts and public assets are copied verbatim.
-- **`package.json` is rebuilt from scratch** with current dependency ranges, so
-  a clone never inherits whatever the in-repo starter pinned.
-- `--template` resolves built-in template ids first, then registry starter ids;
-  an unknown id falls back to `blank`.
-
-Two other consumers read the registry live: the dev server exposes it to
-Studio's picker at `GET /__studio/starters`, returning `listStarters()` verbatim
-(specs/server.md §4.1), and the desktop app imports `listStarters` directly in
-both its Electrobun and Chromium window layers.
+- **Excluded from the copy**: `node_modules`, `dist`, `.cache`, `.jx-cache`, `.git`, and `images.json` (`packages/create/generate.ts`).
+- **`project.json` is preserved**, with only `name` / `url` / `description` / `build.adapter` re-stamped (plus design tokens when the quickstart supplies them). Content, components, layouts and public assets are copied verbatim.
+- **`package.json` is rebuilt from scratch** with current dependency ranges, so a clone never inherits whatever the in-repo starter pinned.
+- `--template` resolves built-in template ids first, then registry starter ids; an unknown id falls back to `blank`.
+
+Two other consumers read the registry live: the dev server exposes it to Studio's picker at `GET /__studio/starters`, returning `listStarters()` verbatim (specs/server.md §4.1), and the desktop app imports `listStarters` directly in both its Electrobun and Chromium window layers.
 
 ## Authoring or modifying a starter
 
 1. Add the `sites/<id>/` tree and a `registry.json` entry with all eight fields.
-2. `bun run schema:generate-all` regenerates every `project.schema.json` and
-   `document.schema.json`. **Always via this script**, never by hand: it runs
-   `schema:clean-roots` first (see below). `bun run schema:verify` proves the
-   result in CI, so a stale entry schema is a red build.
-   `.github/workflows/schemas.yml` also regenerates it and pushes the fix to
-   your branch, with a comment naming the JSON Pointers that moved.
-3. `bun run docs:generate`, because `docs/studio/projects/starters.md` is
-   rendered from `registry.json` by `scripts/docs/generators/starters.ts`.
-   Hand-editing it is a bug; CI diffs the page.
-4. `bun run screenshots:thumbnails`. The `thumbnail` data URI is not
-   hand-authored. The script builds the starter with image optimization off,
-   serves `dist/`, screenshots the hero viewport in headless Chromium, and
-   writes the small JPEG into `registry.json` plus a full-res JPEG into
-   `sites/jxsuite.com/public/starters/<id>.jpg`. (This is why `registry.json` is
-   large.)
+2. `bun run schema:generate-all` regenerates every `project.schema.json` and `document.schema.json`. **Always via this script**, never by hand: it runs `schema:clean-roots` first (see below). `bun run schema:verify` proves the result in CI, so a stale entry schema is a red build. `.github/workflows/schemas.yml` also regenerates it and pushes the fix to your branch, with a comment naming the JSON Pointers that moved.
+3. Nothing for the docs: `docs/studio/projects/starters.md` is rendered from `registry.json` by `scripts/docs/generators/starters.ts` when the site builds, and is never committed (`bun run docs:generate` previews it).
+4. `bun run screenshots:thumbnails`. The `thumbnail` data URI is not hand-authored. The script builds the starter with image optimization off, serves `dist/`, screenshots the hero viewport in headless Chromium, and writes the small JPEG into `registry.json` plus a full-res JPEG into `sites/jxsuite.com/public/starters/<id>.jpg`. (This is why `registry.json` is large.)
 5. Photos, if the starter ships any:
 
    ```sh
    PEXELS_API_KEY=… bun packages/starters/scripts/fetch-photos.ts <site-id> [--force]
    ```
 
-   `images.json` holds `{ site, thumbnail?, images }`, where each image is
-   `{ role, query, orientation?, photoId? }`. The pinned `photoId` makes re-runs
-   fetch the _same_ images; `--force` re-picks even pinned ones. The script
-   upserts a per-site block in `CREDITS.md` between `<!-- site:<id>:start -->`
-   and `<!-- site:<id>:end -->`.
-   Committed output is plain image files, so scaffolded projects have no Pexels
-   or network dependency.
+   `images.json` holds `{ site, thumbnail?, images }`, where each image is `{ role, query, orientation?, photoId? }`. The pinned `photoId` makes re-runs fetch the _same_ images; `--force` re-picks even pinned ones. The script upserts a per-site block in `CREDITS.md` between `<!-- site:<id>:start -->` and `<!-- site:<id>:end -->`. Committed output is plain image files, so scaffolded projects have no Pexels or network dependency.
 
-6. `bun test --isolate` from `packages/starters`. Per-file coverage is gated at
-   99% lines / 99% functions (`bunfig.toml`); `sites/`, `scripts/` and `tests/`
-   are excluded from coverage.
+6. `bun test --isolate` from `packages/starters`. Per-file coverage is gated at 99% lines / 99% functions (`bunfig.toml`); `sites/`, `scripts/` and `tests/` are excluded from coverage.
 
-Adding a starter needs **no** desktop config change:
-`packages/desktop/scripts/verify-bundle.ts` derives its checklist from the
-staged registry, so every new id is covered automatically.
+Adding a starter needs **no** desktop config change: `packages/desktop/scripts/verify-bundle.ts` derives its checklist from the staged registry, so every new id is covered automatically.
 
 ## Hazards
 
-**The shadowed core.** A starter's `package.json` pins _published_ `@jxsuite/*`
-ranges. It must, because it is a template a user scaffolds from, and starters
-are not bun workspace members, so `workspace:^` is unavailable. Iterating a
-starter in Studio runs `bun install` in that root, which materialises a real
-`@jxsuite/schema` beside a workspace far ahead of it. That has already produced
-a starter document schema narrower than the starter's own content, unnoticed for
-six weeks (`scripts/check-shadowed-core.ts` carries the full post-mortem).
-`bun run schema:generate-all` therefore runs `schema:clean-roots`
-(`bun scripts/check-shadowed-core.ts --fix`) first, removing only
-`node_modules/@jxsuite/*` and a stray lockfile. Third-party dependencies stay,
-because the install is what makes the starter preview, and a workspace
-_symlink_ is never removed.
-
-**Never put that cleanup in a starter's `package.json`.** This package publishes
-`sites/`, so those manifests ship to end users; a `postinstall` or `preschema`
-hook there would run on their machine and delete the dependencies they just
-installed. The monorepo has the workspace being shadowed, so the monorepo owns
-the cleanup.
-
-**Do not hand-edit the `@jxsuite/*` ranges in `sites/*/package.json`.**
-release-please rewrites them inside its release commit via `extra-files`; the
-gate is `bun run templates:check` (`templates:sync` to repair).
-
-**Packaged-desktop path contract.** ElectroBun inlines the bun-side JS graph, so
-`import.meta.dirname` resolves to `app/bun/` at runtime. `registry.json` and
-`sites/` must therefore be staged to `bun/registry.json` and `bun/sites` by
-`build.copy` in `packages/desktop/electrobun.config.ts` (specs/desktop.md §7.4).
-
-**The screenshot lane ignores this package's source.** It watches only
-`registry.json` and the six starter roots a shot actually opens
-(`.github/workflows/screenshots.yml`); a registry change arms exactly one shot,
-`new-project`, because that modal's gallery _is_ `listStarters()`.
+**The shadowed core.** A starter's `package.json` pins _published_ `@jxsuite/*` ranges. It must, because it is a template a user scaffolds from, and starters are not bun workspace members, so `workspace:^` is unavailable. Iterating a starter in Studio runs `bun install` in that root, which materialises a real `@jxsuite/schema` beside a workspace far ahead of it. That has already produced a starter document schema narrower than the starter's own content, unnoticed for six weeks (`scripts/check-shadowed-core.ts` carries the full post-mortem). `bun run schema:generate-all` therefore runs `schema:clean-roots` (`bun scripts/check-shadowed-core.ts --fix`) first, removing only `node_modules/@jxsuite/*` and a stray lockfile. Third-party dependencies stay, because the install is what makes the starter preview, and a workspace _symlink_ is never removed.
+
+**Never put that cleanup in a starter's `package.json`.** This package publishes `sites/`, so those manifests ship to end users; a `postinstall` or `preschema` hook there would run on their machine and delete the dependencies they just installed. The monorepo has the workspace being shadowed, so the monorepo owns the cleanup.
+
+**Do not hand-edit the `@jxsuite/*` ranges in `sites/*/package.json`.** release-please rewrites them inside its release commit via `extra-files`; the gate is `bun run templates:check` (`templates:sync` to repair).
+
+**Packaged-desktop path contract.** ElectroBun inlines the bun-side JS graph, so `import.meta.dirname` resolves to `app/bun/` at runtime. `registry.json` and `sites/` must therefore be staged to `bun/registry.json` and `bun/sites` by `build.copy` in `packages/desktop/electrobun.config.ts` (specs/desktop.md §7.4).
+
+**The screenshot lane ignores this package's source.** It watches only `registry.json` and the six starter roots a shot actually opens (`.github/workflows/screenshots.yml`); a registry change arms exactly one shot, `new-project`, because that modal's gallery _is_ `listStarters()`.
 
 ## Versioning
 
-Published to npm as `@jxsuite/starters`. Like every `@jxsuite` package, it ships
-TypeScript source and follows the monorepo's release train (the `starters`
-release-please component). Within the monorepo, `@jxsuite/create` depends on it
-via `workspace:^`. Because consumption is a one-time clone, publishing a new
-version never changes an existing project.
+Published to npm as `@jxsuite/starters`. Like every `@jxsuite` package, it ships TypeScript source and follows the monorepo's release train (the `starters` release-please component). Within the monorepo, `@jxsuite/create` depends on it via `workspace:^`. Because consumption is a one-time clone, publishing a new version never changes an existing project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/starters",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Starter site templates for new Jx projects",
   "license": "MIT",
   "repository": {
@@ -26,9 +26,9 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "devDependencies": {
-    "@jxsuite/parser": "^1.7.0",
-    "@jxsuite/runtime": "^3.1.0",
-    "@jxsuite/schema": "^2.1.0",
+    "@jxsuite/parser": "^1.8.0",
+    "@jxsuite/runtime": "^4.0.0",
+    "@jxsuite/schema": "^2.2.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   }