@homepages/template-kit 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,251 @@
+# @homepages/template-kit
+
+## 0.2.0
+
+### Minor Changes
+
+- e64d4d7: `base.css` no longer ships a reset — Tailwind's preflight (from your entry's
+  `@import "tailwindcss"`) already is one, and the two were duplicating each other. It
+  now carries only the three declarations preflight does not make: font-smoothing,
+  `button { cursor: pointer }`, and `svg { max-width: 100% }`.
+
+  **`base.css` now requires a Tailwind entry on the page.** If a page loads `base.css`
+  without an `@import "tailwindcss"` entry present — a standalone preview, an embed, a
+  hand-written CSS page — it renders fully unreset (UA body margin, bulleted lists,
+  underlined links, unconstrained inline images), and nothing errors to tell you.
+  Confirm every page that loads `base.css` also loads a Tailwind entry.
+
+  `base.css` also no longer references any theme token. The `body` document defaults
+  (font, color, background, size) are now emitted by `compileThemeToCss`, alongside the
+  `:root` block that defines those tokens. **Regenerate and republish your compiled theme
+  CSS.** If you upgrade `base.css` but keep serving a previously-compiled theme
+  stylesheet, that stylesheet still only has the old `:root` block — `body` silently
+  loses `font-family`, `color`, `background`, and `font-size` page-wide, because
+  `base.css` no longer carries them as a fallback. The compiled output's content hash
+  changes.
+
+  The `--tr-space-*` scale is removed — Tailwind's own spacing scale (`p-4`, `gap-6`)
+  was never aliased to it. Any of your CSS still referencing `var(--tr-space-*)` (e.g.
+  `padding: var(--tr-space-4)`) now points at an undefined custom property, which is
+  invalid at computed-value time, so the declaration drops. The `scroll-behavior` /
+  `scroll-padding-top` policy is removed; set it in your own template stylesheet if you
+  have a sticky header.
+
+- a24174f: Every rule-id now resolves to a page. The lint preset and `template-kit check` share one
+  id namespace (`template-kit/<id>`), and each of those ids — all 28 — now has a page at
+  `docs/rules/<id>.md` giving the rule, the reason it exists, and a before/after fix you can
+  copy.
+
+  The docs ship **inside the tarball**, so the loop closes with no network: hit
+  `template-kit/no-hex`, read `node_modules/@homepages/template-kit/docs/rules/no-hex.md`,
+  fix it. That matters most for the coding agents authoring against this kit — an agent that
+  can resolve a failure to its own reference page fixes the violation instead of guessing at
+  it.
+
+  Each ESLint rule also carries `meta.docs.url` pointing at its page, so an editor's "show
+  documentation for this rule" lands on the same file.
+
+  Start at `docs/rules/INDEX.md`. `docs/rules/server-vs-client.md` explains the one concept
+  several rules assume — that server-vs-client is a **per-file** fact, decided by the
+  `"use client"` directive prologue, not by an import graph.
+
+### Patch Changes
+
+- be1507d: Fixed `no-css-import-from-render-path`, which banned the one legal way to get a
+  third-party stylesheet into a section.
+
+  A **bare** `.css` specifier in the render path — `import "swiper/css"` in `Renderer.tsx`,
+  in a marked enhancer, or in any module either one imports — is how a package's CSS reaches
+  the section's cascade layer: the build bundles that import graph precisely to harvest it.
+  The rule flagged it anyway, and its `Fix:` hint sent you to `@import` the stylesheet from
+  `styles.css`, which is never legal there (hand-written CSS is wrapped in `@layer`, where a
+  browser drops an `@import` silently).
+
+  The rule now reports only a **local** stylesheet import — a relative or absolute specifier.
+  That is the real defect: the build already collects every `.css` file in the section folder
+  by filename, so importing one from code ships its rules twice and can corrupt the cascade.
+
+  If you worked around the old rule by moving a package's CSS into a stylesheet `@import`,
+  move it back into the module that needs it — see `docs/rules/no-css-import-from-render-path.md`
+  and `docs/rules/no-bare-css-import.md`, which are the two halves of the same mental model.
+
+## 0.1.0
+
+### Minor Changes
+
+- 46e13a0: `base.css` no longer applies `content-visibility: auto` to off-screen sections on published
+  pages, and no longer defines the `--tr-control-*` tokens.
+
+  `content-visibility` is now opt-in: it carries a `contain: paint` cost that clips in-section
+  overlays, and only a template author knows whether their page needs it. If your page is long
+  and image-heavy, see "Recipe: `content-visibility` on long, image-heavy pages" in
+  `docs/theme-and-css.md` for the rule to add to your own template stylesheet.
+
+  The `--tr-control-*` tokens were unreferenced and are removed.
+
+- b08117b: `ImageValue` now models the shape a renderer actually receives, instead of a
+  CSS-framing model the runtime never implemented.
+
+  **Removed** `crop` (`{ zoom, ox, oy }`) and `focal`. Their doc comments claimed the
+  `<Image>` primitive applied them as a CSS transform / `object-position` — it never
+  did, and no renderer or primitive has ever read either field. Framing is baked into a
+  **pre-cropped derivative asset**: when an image has been cropped, the platform serves
+  that derivative as the slot's `url`, and `<Image>` is a centered `object-cover` over
+  whatever `url` points at. A renderer that read `crop` or `focal` was reading fields
+  that were always absent from the resolved value.
+
+  **Added** `crop_key` — the content-addressed key of the baked crop derivative. It was
+  already on the wire but undeclared here; it is the _provenance_ of `url`, not a second
+  thing to render.
+
+  `rect` and `ar` remain, now labelled **carried, not rendered**: they are the editor's
+  re-edit state (so the cropper can reopen at the last crop), not framing inputs.
+
+  Renderers read only `url`, `alt`, `mobile`, and `responsive`. This matches
+  `ResolvedImage`, the shape the platform emits.
+
+- c003008: Added the **schema system** — the section authoring contract, and the first real
+  surface of this package.
+
+  A section is now fully declarable against the kit: `schema.ts` (slots + options,
+  `as const satisfies SectionSchemaShape`), `fill-spec.ts` (`FillSpecShape`),
+  `fixtures.ts` (`FixtureModule`), and a `Renderer.tsx` whose props are **derived**
+  from the schema via `SectionProps<typeof schema>` rather than hand-written — a
+  required text slot resolves to `string`, an optional one to `string | null`, an
+  enum option to the literal union of its declared values.
+
+  Slots bind to property facts through a **closed vocabulary**: `direct()` accepts
+  only a known fact name and `derived()` only a known transform, so a misspelling is
+  a compile error at the call site instead of a runtime surprise. The vocabulary
+  tables (`SOURCE_FIELDS`, `TRANSFORMS`, `SLOT_TYPE_DESCRIPTORS`) are exported, and
+  changing them is a kit release.
+
+  Also exported: fact-driven variants (`makeResolveVariants`, `TransformInput`), the
+  template composition manifest (`TemplateManifest`), the fixture builders
+  (`buildFixtureSet`), and the image/breakpoint value shapes a renderer receives.
+
+  Everything lands on the package root — `import { … } from "@homepages/template-kit"`.
+  There are no subpath imports for the authoring API.
+
+  Zod is now a runtime dependency (`^3.23.8`).
+
+  Docs: `docs/schema-system.md`.
+
+- 07d5dc8: Added the **contract primitives, theme tokens, and the golden property fixtures** —
+  with the schema system, a section is now authorable end to end against the kit.
+
+  **Primitives.** `Section` (the full-bleed section root), `Slot` and `SlotGroup` (the
+  editor's slot markers), `Image` (responsive `<picture>`/srcset from the platform's
+  image descriptor, with a deterministic empty-state box), and a new `SlotItem`.
+
+  `SlotItem` is the per-item handle inside a collection slot (`object_list`,
+  `image_collection`). It emits `data-slot-item`, which is what makes per-item
+  selection, per-item image cropping, and per-item live surfaces work in the editor —
+  a collection without it is editable only as a whole. The attribute is now declared
+  in the marker contract (`ATTR_SLOT_ITEM`) and emitted by a primitive rather than
+  hand-written as a magic string.
+
+  The primitives are the _only_ components the kit ships, and that is deliberate:
+  each one emits something the platform breaks without. Presentation — headings,
+  links, layout wells, icons, lists — is your template's own JSX.
+
+  **Theme tokens.** `@homepages/template-kit/styles.css` carries the Tailwind v4
+  `@theme` alias layer and the breakpoint ladder; `@homepages/template-kit/base.css`
+  carries the cascade-layer order, the reset, and `.tr-section`. A template supplies
+  the values behind the aliases as a `TokenTheme` (`theme.ts`), compiled by
+  `compileThemeToCss` into the `:root { --tr-*: … }` block its bundle ships.
+
+  Import the token entry **after** Tailwind, and import Tailwind exactly once — a
+  second `@import "tailwindcss"` anywhere in the graph double-emits the preflight
+  reset:
+
+  ```css
+  @import "tailwindcss";
+  @import "@homepages/template-kit/styles.css";
+  ```
+
+  **Golden fixtures.** `sampleProperty` and friends (`sampleContacts`, `samplePois`,
+  `sampleAmenities`, `allPhotos`, `mkResponsive`) — a realistic 12-unit building with
+  long unit labels, a reserved unit and a missing price. Preview is only as honest as
+  the data behind it; build your `fixtures.ts` on these rather than on lorem ipsum.
+
+  **Breaking within 0.x:** the type formerly exported as `Slot` (the slot-definition
+  union) is now `SlotDefinition`. `Slot` is the primitive component.
+
+- 35b0939: Added `@homepages/template-kit/eslint` — the flat-config ESLint preset for section
+  authoring. Eleven rules, all syntactic (no type-aware linting, so "zero extra config"
+  holds), catch the mistakes specific to writing a HomePages section template: reading
+  the clock or randomness (`no-nondeterminism`), effects/state/handlers/browser globals
+  outside a `"use client"` island (`no-client-runtime-in-server`), a prop crossing to an
+  island that can't survive JSON serialization (`serializable-island-props`), a hard-coded
+  colour where a theme token belongs (`no-hex`), and seven more covering the contract
+  files, slot markers, and raw-CSS boundaries a section must respect.
+
+  Consume it as:
+
+  ```js
+  import kit from "@homepages/template-kit/eslint";
+  export default kit;
+  ```
+
+  `@typescript-eslint/parser` is now a real `dependency` (not only a devDependency) —
+  the preset wires it directly so a consumer's `eslint.config.mjs` needs no parser
+  setup of its own.
+
+- 2a32639: Islands: interactivity is now an ordinary React component marked "use client". Adds the
+  island contract and marker to the main entry, a new `./island-runtime` loader that
+  hydrates each island as its own React root, and a new `./browser` subpath with the
+  site-config and signed-ingest helpers for published pages.
+- 96356b5: The published barrel now tree-shakes, and the golden fixtures move to their own subpath.
+
+  The build previously collapsed the primitives, the schema system, zod, the theme compiler
+  and the sample-property fixtures into a single chunk that `dist/index.js` only re-exported.
+  Because a consumer's bundler can only tree-shake at module granularity, importing one
+  primitive pulled in all of it: `import { Section }` cost **84,755 B** and inlined zod plus
+  the golden fixture dataset — agent phone numbers, listing prices, lot sizes — into every
+  section's published renderer.
+
+  The build is now unbundled (one output module per source module), so the import graph is
+  honest. `import { Section }` is **202 B**; `import { makeResolveVariants }` is **179 B**.
+  Neither carries zod or fixture data.
+
+  **Breaking:** `sampleProperty`, `sampleContacts`, `samplePois`, `sampleAmenities`,
+  `allPhotos`, `mkResponsive`, `sampleHeroSlots` and the `PhotoFixture` / `PoiFixture` /
+  `ContactFixture` / `AmenityItem` types are no longer exported from the root barrel. Import
+  them from `@homepages/template-kit/fixtures`:
+
+  ```diff
+  -import { sampleProperty } from "@homepages/template-kit";
+  +import { sampleProperty } from "@homepages/template-kit/fixtures";
+  ```
+
+  Dev-only sample data must not be reachable from a renderer's import graph at all: a
+  section's published bundle is an immutable, publicly readable artifact. Import fixtures
+  from `fixtures.ts`, never from `Renderer.tsx`. Everything else on the root barrel — the
+  primitives, the schema types, `makeResolveVariants`, `compileThemeToCss`, `KIT_VERSION`,
+  the marker constants, the islands contract — is unchanged.
+
+  The kit's `styles.css` also narrows its Tailwind `@source` scan to the shipped
+  `primitives/` modules, which are the only ones that emit markup. This drops 8 dead
+  utilities and 19 stray `@property` registrations that were being compiled out of the CLI's
+  and the ESLint preset's doc comments into consumers' stylesheets.
+
+### Patch Changes
+
+- bb15161: Hardened the release pipeline that produces this package, with no change to the
+  authoring API. Packing or publishing now always rebuilds first, so the tarball
+  can never ship a stale `dist/`. The tsconfig preset shipped at
+  `@homepages/template-kit/tsconfig` no longer leaks this repo's own `exclude`
+  list or forces `noEmit` onto consumers who extend it. `CHANGELOG.md` is now
+  included in the published tarball, so you can read what changed in a given
+  version without leaving `node_modules`. The docs shipped alongside the package
+  no longer reference this project's private internal repo layout.
+
+## 0.0.1
+
+### Patch Changes
+
+- c1d3127: Package skeleton: the published boundary and its hygiene gates. Ships the exports
+  map (root entry, ESLint flat-config preset, tsconfig preset, Tailwind v4 tokens
+  CSS), the `template-kit` CLI with its commands stubbed, and the changesets → npm
+  trusted-publishing release pipeline. No authoring surface yet.

package/README.md

@@ -3,9 +3,10 @@
 The authoring surface for HomePages marketing-section templates: schema system,
 contract primitives, theme tokens, and the `template-kit` CLI.
 
-**Status: 0.0.x — package skeleton.** The authoring surface is still being
-extracted, and the CLI commands are not implemented yet. What exists today is
-the published package boundary and its hygiene gates.
+**Status: 0.0.x.** The **schema system** (the section authoring contract and the closed
+vocabulary it validates against), the **contract primitives**, and the **theme tokens**
+are complete — a section is authorable end to end against the kit. The `template-kit`
+CLI's commands are still being extracted.
 
 ## Install
 
@@ -15,35 +16,100 @@ npm install @homepages/template-kit react react-dom
 
 React 19 is a **peer dependency** — the kit never bundles its own copy.
 
+## Authoring a section
+
+A section is four files: `schema.ts` (slots + options), `fill-spec.ts` (how AI
+fills them), `fixtures.ts` (preview content), and `Renderer.tsx` (markup, with
+props **derived** from the schema).
+
+```ts
+import { direct, type SectionProps, type SectionSchemaShape } from "@homepages/template-kit";
+
+export const schema = {
+  meta: { displayName: "Hero" },
+  slots: {
+    headline: { type: "text", required: true, produced_by: "headline_text" },
+    listing_status: { type: "select", required: false, source: direct("listing_intent") },
+  },
+} as const satisfies SectionSchemaShape;
+
+export type Props = SectionProps<typeof schema>; // slots.headline is `string`
+```
+
+Property facts come from a closed vocabulary, so `direct("listing_intentt")` is a
+compile error, not a runtime surprise. Full contract:
+**[docs/schema-system.md](docs/schema-system.md)**.
+
+Your fixtures build on the kit's golden property dataset (`sampleProperty`, `allPhotos`,
+`samplePois`, …) — a realistic 12-unit building, long labels and missing values included.
+
+## The primitives
+
+The kit ships **five components and nothing else**: `Section` (the full-bleed section
+root), `Slot` and `SlotItem` and `SlotGroup` (the editor's marker attributes), and
+`Image` (responsive `<picture>` + a deterministic empty-state box). Each earns its place
+by emitting something the platform breaks without. Presentation — headings, links,
+layout, icons — is your template's own JSX.
+
+```tsx
+import { Image, Section, Slot, SlotItem } from "@homepages/template-kit";
+```
+
+Full contract: **[docs/primitives.md](docs/primitives.md)**.
+
 ## Exports
 
 | Entry | Use |
 |---|---|
-| `@homepages/template-kit` | Authoring API (schema, primitives) |
-| `@homepages/template-kit/styles.css` | Tailwind v4 theme tokens + kit source registration |
+| `@homepages/template-kit` | Authoring API — schema system, primitives, marker contract, theme types, and the golden fixtures |
+| `@homepages/template-kit/island-runtime` | Browser loader that hydrates a page's islands |
+| `@homepages/template-kit/browser` | Browser helpers for published pages (site config, signed ingest) |
+| `@homepages/template-kit/styles.css` | Tailwind v4 theme tokens, the breakpoint ladder, kit source registration |
+| `@homepages/template-kit/base.css` | Cascade-layer order, the three reset gaps Tailwind's preflight leaves, `.tr-section`, and the motion tokens |
 | `@homepages/template-kit/eslint` | ESLint flat-config preset |
 | `@homepages/template-kit/tsconfig` | tsconfig preset (`"extends"`) |
 
-The CSS entry does **not** import Tailwind. Import it *after* Tailwind in your entry:
+The authoring API has **no subpath imports** — one specifier for everything you
+write a section against. The two CSS entries are the deliberate exception.
+
+`styles.css` does **not** import Tailwind. Import it *after* Tailwind in your entry:
 
 ```css
 @import "tailwindcss";
 @import "@homepages/template-kit/styles.css";
 ```
 
-Two `@import "tailwindcss"` in one graph double-emits preflight.
+Two `@import "tailwindcss"` in one graph double-emits preflight. `base.css` is not part
+of that entry — it loads as its own stylesheet on the page. `base.css` ships no reset
+of its own — it depends on the preflight your entry's `@import "tailwindcss"` brings.
+Both must be on the page. Full contract:
+**[docs/theme-and-css.md](docs/theme-and-css.md)**.
+
+## Rules
+
+The lint preset and the `template-kit check` CLI share one id namespace,
+`template-kit/<id>`. A rule-id printed by either resolves to a page —
+`docs/rules/<id>.md` — giving the rule, the reason it exists, and a before/after fix.
+Start at **[docs/rules/INDEX.md](docs/rules/INDEX.md)**; the full doc set is routed
+from **[docs/INDEX.md](docs/INDEX.md)**.
 
 ## Development
 
 ```bash
 npm install
-npm run check     # typecheck + lint + test + build + publint + attw + consumer gate
+npm run check     # typecheck + lint + build + island-size gate + test + publint + attw + consumer gate
 ```
 
 `npm run verify:consumer` is the boundary gate: it packs the kit, installs the
-tarball into a scratch project, and asserts that types resolve, that Tailwind's
-cross-package `@source` scan reaches the shipped `dist`, and that only one React
-ends up in the tree. Run it before every release.
+tarball into a scratch project, and asserts that types resolve; that a real section
+triple typechecks against the installed package, with a misspelled property fact or
+slot key still failing to compile; that Tailwind's cross-package `@source` scan
+reaches the shipped `dist`; and that only one React ends up in the tree. Run it
+before every release.
+
+The island loader (`@homepages/template-kit/island-runtime`) has its own gate,
+`npm run size:islands`: it must stay under 3072 B gzip and never import
+`react`/`react-dom` statically, so a page with no islands loads no React.
 
 ## Releasing
 

package/dist/base.css

@@ -0,0 +1,64 @@
+@layer theme, base, components, sections, template, utilities;
+
+/* @homepages/template-kit — the base stylesheet every template's page loads.
+ *
+ * Exported as `@homepages/template-kit/base.css`. It is NOT part of the Tailwind
+ * entry (that is styles.css); it ships as its own stylesheet on the page.
+ *
+ * Contains:
+ *   - The cascade-layer order declaration above — the one place it is stated
+ *   - The three reset gaps Tailwind's preflight leaves (below)
+ *   - The section box model (.tr-section, emitted by the <Section> primitive)
+ *   - Universal tokens: motion
+ *
+ * REQUIRES A TAILWIND ENTRY ON THE PAGE. Your entry's `@import "tailwindcss"` brings
+ * Tailwind's preflight, and preflight does the reset: box-sizing, margin/padding,
+ * list-style, the button and anchor resets, display:block on replaced elements. This
+ * file only fills the three gaps preflight leaves. Ship base.css without a Tailwind
+ * entry and you get an unreset page.
+ *
+ * NOT here: anything a template owns. Colors, fonts, type, radii, shadows and layout
+ * — and the `body` document defaults that apply them — all come from your theme.ts,
+ * compiled by compileThemeToCss. This file references no theme token at all.
+ */
+
+/* ----- Reset gaps ------------------------------------------------------- *
+ * The three declarations Tailwind's preflight does NOT make. Each is load-bearing:
+ * delete one and your page changes.
+ *
+ * Wrapped in `@layer base` so Tailwind's utilities (which compile into
+ * `@layer utilities`) win over these element defaults. Unlayered, `button { cursor:
+ * pointer }` would beat a layered `.cursor-default` utility outright — unlayered
+ * always wins over layered in the cascade.
+ */
+
+@layer base {
+  /* preflight carries no font-smoothing rule at all */
+  body { -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
+  /* Tailwind v4 deliberately leaves buttons at the UA default `cursor: default` */
+  button { cursor: pointer; }
+  /* preflight caps max-width on img and video, but not on svg */
+  svg { max-width: 100%; }
+}
+
+/* ----- Primitives ------------------------------------------------------- */
+
+/* The full-bleed section root, emitted by the <Section> primitive. Always 100% wide
+ * with zero padding/margin, so adjacent sections butt edge-to-edge and a page composes
+ * as a vertical stack with no framework-injected whitespace. A section brings its own
+ * background and internal padding. */
+.tr-section {
+  display: block;
+  width: 100%;
+  padding: 0;
+  margin: 0;
+}
+
+/* ----- Universal tokens ------------------------------------------------- */
+
+:root {
+  /* Motion */
+  --tr-duration-fast: 150ms;
+  --tr-duration-base: 250ms;
+  --tr-ease: cubic-bezier(0.2, 0.8, 0.2, 1);
+}

package/dist/browser.d.ts

@@ -0,0 +1,26 @@
+//#region src/browser/site-config.d.ts
+interface SiteConfig {
+  siteId: string;
+  siteSecret: string;
+  ingestBase: string;
+}
+/** Read the per-site config a published page embeds as `#tr-site-config`. Null when absent or incomplete. */
+declare function readSiteConfig(): SiteConfig | null;
+/**
+ * Decode hex to bytes. Always ArrayBuffer-backed (never SharedArrayBuffer), so the
+ * result satisfies the BufferSource parameter of crypto.subtle.importKey — but that
+ * generic stays out of this public signature: on TypeScript < 5.7, `Uint8Array` isn't
+ * generic at all, and writing `Uint8Array<ArrayBuffer>` here would fail every
+ * consumer's build below that floor (TS2315) for a detail only this module's own
+ * `crypto.subtle.importKey` call needs.
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+declare function bytesToHex(buf: ArrayBuffer): string;
+declare function hmacHex(secretHex: string, message: string): Promise<string>;
+/**
+ * The signed header set every ingest request carries:
+ * `X-Signature` = hex(hmac_sha256(siteSecret, `${unixSeconds}.${body}`)).
+ */
+declare function signedIngestHeaders(config: SiteConfig, body: string): Promise<Record<string, string>>;
+//#endregion
+export { SiteConfig, bytesToHex, hexToBytes, hmacHex, readSiteConfig, signedIngestHeaders };

package/dist/browser.js

@@ -0,0 +1,55 @@
+//#region src/browser/site-config.ts
+/** Read the per-site config a published page embeds as `#tr-site-config`. Null when absent or incomplete. */
+function readSiteConfig() {
+	const el = document.getElementById("tr-site-config");
+	if (!el?.textContent) return null;
+	try {
+		const config = JSON.parse(el.textContent);
+		if (!config.siteId || !config.siteSecret || !config.ingestBase) return null;
+		return config;
+	} catch {
+		return null;
+	}
+}
+/**
+* Decode hex to bytes. Always ArrayBuffer-backed (never SharedArrayBuffer), so the
+* result satisfies the BufferSource parameter of crypto.subtle.importKey — but that
+* generic stays out of this public signature: on TypeScript < 5.7, `Uint8Array` isn't
+* generic at all, and writing `Uint8Array<ArrayBuffer>` here would fail every
+* consumer's build below that floor (TS2315) for a detail only this module's own
+* `crypto.subtle.importKey` call needs.
+*/
+function hexToBytes(hex) {
+	if (hex.length % 2 !== 0) throw new Error("hexToBytes: odd-length hex string");
+	if (!/^[0-9a-fA-F]*$/.test(hex)) throw new Error("hexToBytes: invalid hex string");
+	const out = new Uint8Array(/* @__PURE__ */ new ArrayBuffer(hex.length / 2));
+	for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+	return out;
+}
+function bytesToHex(buf) {
+	return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function hmacHex(secretHex, message) {
+	const key = await crypto.subtle.importKey("raw", hexToBytes(secretHex), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return bytesToHex(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message)));
+}
+/**
+* The signed header set every ingest request carries:
+* `X-Signature` = hex(hmac_sha256(siteSecret, `${unixSeconds}.${body}`)).
+*/
+async function signedIngestHeaders(config, body) {
+	const ts = Math.floor(Date.now() / 1e3).toString();
+	const signature = await hmacHex(config.siteSecret, `${ts}.${body}`);
+	return {
+		"Content-Type": "application/json",
+		"X-Site-Id": config.siteId,
+		"X-Timestamp": ts,
+		"X-Signature": signature
+	};
+}
+
+//#endregion
+export { bytesToHex, hexToBytes, hmacHex, readSiteConfig, signedIngestHeaders };

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as KIT_VERSION } from "./src-dZr5N30y.js";
+import { KIT_VERSION } from "./index.js";
 
 //#region src/cli/index.ts
 /**

package/dist/contracts/image-descriptor.d.ts

@@ -0,0 +1,17 @@
+//#region src/contracts/image-descriptor.d.ts
+interface ResponsiveSource {
+  /** Image MIME type: 'image/avif' | 'image/webp' | 'image/jpeg' | 'image/png'. */
+  type: string;
+  /** "<presigned-url> 320w, … 2048w" — rungs ascending by ACTUAL width. */
+  srcset: string;
+}
+interface ResponsiveImage {
+  /** Per-format candidate sets, ordered preferred→fallback: avif, webp, jpeg, png. */
+  sources: ResponsiveSource[];
+  /** Ceiling-rung (MAX edge) actual width — drives <img> width/aspect/sizes. */
+  width: number;
+  /** Ceiling-rung actual height. */
+  height: number;
+}
+//#endregion
+export { ResponsiveImage, ResponsiveSource };

package/dist/contracts/markers.d.ts

@@ -0,0 +1,20 @@
+//#region src/contracts/markers.d.ts
+/** Wrapper marker the editor resolves a slot from (`Slot`, primitive `slotId`). */
+declare const ATTR_SLOT_ID = "data-slot-id";
+/** Marks the immediate text-leaf child of a `textLeaf` slot. */
+declare const ATTR_SLOT_TEXT_LEAF = "data-slot-text-leaf";
+/** Wraps a set of slots edited/regenerated as one unit (`SlotGroup`). */
+declare const ATTR_SLOT_GROUP = "data-slot-group";
+/**
+ * Zero-based index of one item inside a collection slot (`SlotItem`) — the
+ * per-item handle for `object_list` / `image_collection` slots. The editor
+ * resolves per-item selection, live enhancer surfaces, and per-item image
+ * crops against it, scoped to the enclosing `ATTR_SLOT_ID` element.
+ */
+declare const ATTR_SLOT_ITEM = "data-slot-item";
+/** Per-section-instance identity on the section root. */
+declare const ATTR_SECTION_INSTANCE_ID = "data-section-instance-id";
+/** Opt-in hook telling an enhancer to attach to this element. */
+declare const ATTR_TR_ENHANCE = "data-tr-enhance";
+//#endregion
+export { ATTR_SECTION_INSTANCE_ID, ATTR_SLOT_GROUP, ATTR_SLOT_ID, ATTR_SLOT_ITEM, ATTR_SLOT_TEXT_LEAF, ATTR_TR_ENHANCE };

package/dist/contracts/markers.js

@@ -0,0 +1,21 @@
+//#region src/contracts/markers.ts
+/** Wrapper marker the editor resolves a slot from (`Slot`, primitive `slotId`). */
+const ATTR_SLOT_ID = "data-slot-id";
+/** Marks the immediate text-leaf child of a `textLeaf` slot. */
+const ATTR_SLOT_TEXT_LEAF = "data-slot-text-leaf";
+/** Wraps a set of slots edited/regenerated as one unit (`SlotGroup`). */
+const ATTR_SLOT_GROUP = "data-slot-group";
+/**
+* Zero-based index of one item inside a collection slot (`SlotItem`) — the
+* per-item handle for `object_list` / `image_collection` slots. The editor
+* resolves per-item selection, live enhancer surfaces, and per-item image
+* crops against it, scoped to the enclosing `ATTR_SLOT_ID` element.
+*/
+const ATTR_SLOT_ITEM = "data-slot-item";
+/** Per-section-instance identity on the section root. */
+const ATTR_SECTION_INSTANCE_ID = "data-section-instance-id";
+/** Opt-in hook telling an enhancer to attach to this element. */
+const ATTR_TR_ENHANCE = "data-tr-enhance";
+
+//#endregion
+export { ATTR_SECTION_INSTANCE_ID, ATTR_SLOT_GROUP, ATTR_SLOT_ID, ATTR_SLOT_ITEM, ATTR_SLOT_TEXT_LEAF, ATTR_TR_ENHANCE };