cursedbelt-core 1.0.0

package/src/core/site/siteCopy.ts

@@ -0,0 +1,115 @@
+/**
+ * The marketing-site copy contract — owner decision **D36** (2026-07-27).
+ *
+ * ## What D36 actually asked for
+ *
+ * The owner's answer to "give me the words" was: *"I want to see it first, use
+ * your judgment for now. Make an admin section where I can edit them. Put in
+ * placeholders or good values now. Values I edit are in the db. I potentially
+ * switch to hardcoding them if this is too slow for the page loads to get and
+ * fill in the text, caching may help."*
+ *
+ * That decomposes into one contract with three consumers, and this module is
+ * the single source all three import so they can never disagree about what a
+ * key is or what its default says:
+ *
+ *   1. **The static site build** (`site/build.ts`) BAKES every default into the
+ *      emitted HTML. Crawlers, Lighthouse and a JS-disabled visitor see a
+ *      complete page; SEO never depends on a fetch.
+ *   2. **The server** (`guard.mixin.ts` + `drivers/siteCopy.ts`) stores the
+ *      owner's EDITS — only the overridden keys — and serves them from a
+ *      cacheable public endpoint.
+ *   3. **The admin panel** lists every key with its default beside the stored
+ *      value, so "reset" is a visible diff rather than a guess.
+ *
+ * The owner's "switch to hardcoding" exit ramp is already built: the bake step
+ * IS the hardcoding; deleting the page's overlay fetch is the whole switch.
+ *
+ * ## Why a closed key list rather than free-form KV
+ *
+ * Every key here has a home in the page template. A free-form store would let
+ * an edit succeed against a key nothing renders — a silent no-op the owner
+ * would read as "editing is broken". `setSiteCopyValue` refuses unknown keys,
+ * so a typo is a 400 naming the valid keys, not a row nobody reads.
+ *
+ * `seo.*` keys are baked-only by nature: the runtime overlay swaps visible
+ * text nodes, and a crawler never runs it — so an edited `seo.title` takes
+ * effect at the NEXT site build. The admin panel says so per key
+ * ({@link SITE_COPY_BAKED_ONLY}).
+ */
+
+/** Ceiling on one stored value. The longest default is ~400 chars; 4000 leaves
+ *  room for a generous rewrite while refusing a pasted novel (the value rides
+ *  an HTTP header-cached JSON body every visitor may fetch). */
+export const SITE_COPY_MAX_VALUE_LENGTH = 4000;
+
+/**
+ * Every editable string on the marketing page, with the shipped default.
+ * Ordered as the page reads, because this order is also the admin panel's.
+ */
+export const SITE_COPY_DEFAULTS = {
+  'product.name': 'Cursed Alchemy',
+  'product.tagline': 'Build real, multi-user web applications visually. Identity, data, and media included.',
+
+  'seo.title': 'Cursed Alchemy — Build visual architectures. Deploy production apps.',
+  'seo.description':
+    'A visual studio engineered for resilient web applications. Combine core modules — user auth, document databases, media storage — on a live canvas that validates your architecture and deploys production-ready apps.',
+
+  'hero.title': 'Build visual architectures. Deploy production apps.',
+  'hero.subtitle':
+    'A visual studio engineered for building resilient web applications. Combine core modules—like user auth, databases, and media storage—on a live canvas that validates and deploys your stack automatically.',
+  'hero.cta': 'Coming soon — sign-ups open shortly.',
+
+  'feature.studio.kicker': 'Infrastructure Engine',
+  'feature.studio.title': 'Orchestrated for Production',
+  'feature.studio.body':
+    'Drag core infrastructure onto a live canvas and connect it seamlessly. The studio analyzes structural dependencies in real time, catching broken configurations instantly — before they ever reach production.',
+  'feature.engines.kicker': 'Unified Ecosystem',
+  'feature.engines.title': 'Sovereign Infrastructure, Built In',
+  'feature.engines.body':
+    'Native authentication, relational databases, media vaults, and productivity tooling ship as one unified ecosystem — maintained centrally, running at peak performance, with no brittle third-party plugins to babysit.',
+  'feature.ownership.kicker': 'Data Governance',
+  'feature.ownership.title': 'Complete Ownership of Your Architecture',
+  'feature.ownership.body':
+    'Every workspace runs in strict multi-tenant isolation with comprehensive change logs, automated backups, and total data portability. Your environment belongs to you — zero vendor lock-in. Ever.',
+
+  'modules.kicker': 'Batteries Included',
+  'modules.title': 'Every core module. One canvas.',
+  'modules.body':
+    'User accounts, document databases, media vaults, scheduling, email, and staging sandboxes — first-party engines that snap together and ship as one verified stack.',
+
+  'plans.heading': 'Plans',
+  'plans.note':
+    'Pricing is being finalized. Join today as an early tester to secure free access and help shape the product roadmap.',
+  'plan.free.name': 'Explorer',
+  'plan.free.price': 'Free',
+  'plan.free.body': '• Build and host one workspace\n• Access to foundational modules',
+  'plan.pro.name': 'Alchemist',
+  'plan.pro.price': 'Coming soon',
+  'plan.pro.body': '• Unlock all advanced modules\n• Expanded storage limits\n• Priority developer support',
+  'plan.team.name': 'Guild',
+  'plan.team.price': 'Coming soon',
+  'plan.team.body':
+    '• Collaborative team workspaces\n• Role-based access control (RBAC)\n• Full system audit logs',
+
+  'about.heading': 'About',
+  'about.body':
+    'Cursed Alchemy is built independently with an uncompromising focus on core infrastructure—authentication, isolation, secure backups, and audit trails. We master the complex foundational architecture so you can focus entirely on your unique user experience.',
+
+  'signin.label': 'Sign in',
+  'footer.note': '© Cursed Alchemy. All rights reserved.',
+} as const;
+
+export type SiteCopyKey = keyof typeof SITE_COPY_DEFAULTS;
+
+export const SITE_COPY_KEYS = Object.freeze(Object.keys(SITE_COPY_DEFAULTS)) as readonly SiteCopyKey[];
+
+export const isSiteCopyKey = (value: string): value is SiteCopyKey =>
+  Object.hasOwn(SITE_COPY_DEFAULTS, value);
+
+/**
+ * Keys the runtime overlay cannot apply (they live in `<head>`, which only a
+ * rebuild re-emits). The admin panel labels these "applies at next site
+ * publish" instead of pretending the edit is live.
+ */
+export const SITE_COPY_BAKED_ONLY: readonly SiteCopyKey[] = Object.freeze(['seo.title', 'seo.description']);

package/src/core/slots.ts

@@ -0,0 +1,38 @@
+/**
+ * The Slot registry (02 §6.1) — a closed set. A fill targeting anything else is
+ * V1 `slot-unknown`, which is the difference between "my panel silently never
+ * rendered" and a build error naming the typo.
+ */
+export const SLOTS = [
+  'HeaderLeft',
+  'HeaderRight', // app chrome (auth UI renders here by default)
+  'SidebarTop',
+  'SidebarFooter',
+  'InspectorTab', // fills add tabs: {tabTitle, panel}
+  'DashboardWidget', // SystemUtility dashboard grid cells
+  'ItemContextMenu',
+  'EditorToolbar',
+  'StatusBar',
+] as const;
+
+export type SlotId = (typeof SLOTS)[number];
+
+const SLOT_SET: ReadonlySet<string> = new Set<string>(SLOTS);
+
+export const isSlotId = (value: string): value is SlotId => SLOT_SET.has(value);
+
+/**
+ * Fixed z-index bands (02 §6.2). Literal z-index values anywhere else are a lint
+ * error; the Portal Provider assigns `bandBase + stackDepth` inside the band so
+ * two engines opening dialogs at once stack deterministically.
+ */
+export const Z_BANDS = {
+  content: 0,
+  sticky: 100,
+  overlay: 1000,
+  popover: 1100,
+  toast: 1200,
+  critical: 1300, // GuardEngine lock screen — always wins
+} as const;
+
+export type ZBand = keyof typeof Z_BANDS;

package/src/core/styles/constructableSheet.ts

@@ -0,0 +1,86 @@
+/**
+ * The Constructable Stylesheet adopter (02 §5.2, ruling J2-4).
+ *
+ * Engines carrying third-party global stylesheets declare
+ * `cssIsolation: 'shadow'` and mount inside a ShadowRoot. The naive way to give
+ * those roots the framework's tokens is to inline a `<style>` copy of the sheet
+ * into each one — which duplicates the entire Tailwind/token CSSOM per instance.
+ * A dashboard with eight shadow panels then pays eight full parses and eight
+ * allocations, and every theme change re-parses all eight.
+ *
+ * Instead the shell compiles the sheet **exactly once at boot** into an
+ * immutable `CSSStyleSheet` and every shadow boundary adopts it **by
+ * reference**. The browser shares one CSSOM allocation across N boundaries, so a
+ * multi-panel dashboard costs one sheet, not N.
+ *
+ * A shadow root that inlines its own copy is V5 ERROR `stylesheet-duplication`.
+ */
+
+let sharedSheet: CSSStyleSheet | null = null;
+
+/** Does this environment support Constructable Stylesheets? */
+export const supportsConstructableStylesheets = (): boolean =>
+  typeof CSSStyleSheet !== 'undefined' &&
+  typeof (CSSStyleSheet.prototype as { replaceSync?: unknown }).replaceSync === 'function' &&
+  typeof ShadowRoot !== 'undefined' &&
+  'adoptedStyleSheets' in ShadowRoot.prototype;
+
+/**
+ * Compile the shared sheet. Call ONCE at boot with the framework's
+ * token/Tailwind CSS text; later calls are ignored so a second caller cannot
+ * silently replace the sheet every boundary is already pointing at.
+ */
+export function initSharedStyleSheet(cssText: string): CSSStyleSheet | null {
+  if (sharedSheet !== null) return sharedSheet;
+  if (!supportsConstructableStylesheets()) return null;
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(cssText);
+  sharedSheet = sheet;
+  return sheet;
+}
+
+export const getSharedStyleSheet = (): CSSStyleSheet | null => sharedSheet;
+
+/**
+ * Adopt the shared sheet (plus an optional instance-local one) into a shadow
+ * root — **by reference, never by copy**.
+ *
+ * Returns false when the platform lacks the API; the caller then falls back to a
+ * single `<link>` in the shadow root, which still avoids inlining the text N
+ * times.
+ */
+export function adoptSharedStyles(root: ShadowRoot, instanceLocalSheet?: CSSStyleSheet): boolean {
+  if (sharedSheet === null || !supportsConstructableStylesheets()) return false;
+  const sheets = instanceLocalSheet ? [sharedSheet, instanceLocalSheet] : [sharedSheet];
+  // Assigning the shared object itself is the entire point — a `.slice()` of its
+  // rules into a fresh sheet would reintroduce the per-instance allocation.
+  root.adoptedStyleSheets = sheets;
+  return true;
+}
+
+/**
+ * Build an instance-local sheet for an engine's own scoped CSS. Kept separate
+ * from the shared one so a per-instance override never mutates the object every
+ * other boundary adopted.
+ */
+export function createInstanceStyleSheet(cssText: string): CSSStyleSheet | null {
+  if (!supportsConstructableStylesheets()) return null;
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(cssText);
+  return sheet;
+}
+
+/** Test seam — drops the shared sheet so a suite can re-init cleanly. */
+export const resetSharedStyleSheet = (): void => {
+  sharedSheet = null;
+};
+
+/**
+ * The `@scope` wrapper for `cssIsolation: 'scope'`.
+ *
+ * Lighter than a shadow root: the subtree keeps inheriting the app's tokens
+ * (a shadow boundary would cut them off), while a reset stops the third-party
+ * sheet's global selectors from leaking outward.
+ */
+export const scopedCss = (scopeSelector: string, cssText: string): string =>
+  `@scope (${scopeSelector}) { :scope { all: revert-layer; } ${cssText} }`;

package/src/core/tokens/registry.spec.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'bun:test';
+import { z } from 'zod';
+import {
+  BASE_TOKENS,
+  compareSchemaShapes,
+  createTokenRegistry,
+  describeSchema,
+  isExtensionTokenId,
+  stagingPluginOf,
+  type TokenDef,
+  TokenRegistry,
+} from './registry';
+
+const token = (over: Partial<TokenDef> & { id: string }): TokenDef => ({
+  mode: 'value',
+  description: 'fixture token',
+  schema: z.object({ id: z.string() }),
+  sample: { id: 'x' },
+  ...over,
+});
+
+describe('base registry', () => {
+  it('constructs with every base token and rejects nothing', () => {
+    const registry = createTokenRegistry();
+    expect(registry.ids().length).toBe(BASE_TOKENS.length);
+    for (const base of BASE_TOKENS) expect(registry.has(base.id)).toBe(true);
+  });
+
+  it('every base token sample satisfies its own schema (the V7.4 wire smoke payload)', () => {
+    for (const base of BASE_TOKENS) expect(base.schema.safeParse(base.sample).success).toBe(true);
+  });
+
+  it('refuses a base token in the reserved staging namespace', () => {
+    expect(() => new TokenRegistry([token({ id: 'x-habits:mark' })])).toThrow(/token-namespace-violation/);
+  });
+});
+
+describe('lattice membership (04 V3)', () => {
+  const registry = createTokenRegistry();
+
+  it('is reflexive and transitive over subtypeOf', () => {
+    expect(registry.isSubtype('media:videos', 'media:videos')).toBe(true);
+    expect(registry.isSubtype('media:videos', 'media:items')).toBe(true);
+    expect(registry.isSubtype('media:items', 'media:videos')).toBe(false);
+  });
+
+  it('connects a narrower producer to a wider consumer — string equality is retired', () => {
+    expect(registry.canConnect('media:videos', 'media:items').ok).toBe(true);
+    expect(registry.canConnect('media:photos', 'media:items').ok).toBe(true);
+    const wrongWay = registry.canConnect('media:items', 'media:videos');
+    expect(wrongWay.ok).toBe(false);
+    expect(wrongWay.reason).toBe('not-a-subtype');
+  });
+
+  it('refuses signal↔value mismatches', () => {
+    const mismatch = registry.canConnect('signal:refresh', 'text:content');
+    expect(mismatch.ok).toBe(false);
+    expect(mismatch.reason).toBe('mode-mismatch');
+  });
+
+  it('names the unknown side when a token is not registered', () => {
+    expect(registry.canConnect('nope:thing', 'media:items').reason).toBe('unknown-produced');
+    expect(registry.canConnect('media:items', 'nope:thing').reason).toBe('unknown-consumed');
+  });
+});
+
+describe('staging extension laws', () => {
+  it('accepts a namespaced extension that narrows a core token', () => {
+    const registry = createTokenRegistry();
+    const issues = registry.registerAll(
+      [token({ id: 'x-habits:mark', mode: 'signal', subtypeOf: 'signal:refresh', schema: z.object({ habitId: z.string() }), sample: { habitId: 'h' } })],
+      { origin: 'staging', path: '/staging/plugin-habits/tokens.token-extension.ts' },
+    );
+    expect(issues).toEqual([]);
+    expect(registry.canConnect('x-habits:mark', 'signal:refresh').ok).toBe(true);
+  });
+
+  it('reports a redeclaration of a core token as a collision, not a namespace problem', () => {
+    const registry = createTokenRegistry();
+    const issues = registry.registerAll([token({ id: 'media:videos' })], { origin: 'staging' });
+    expect(issues.map((i) => i.code)).toEqual(['token-collision']);
+  });
+
+  it('rejects an un-namespaced staging token', () => {
+    const registry = createTokenRegistry();
+    const issues = registry.registerAll([token({ id: 'habits:mark' })], { origin: 'staging' });
+    expect(issues.map((i) => i.code)).toEqual(['token-namespace-violation']);
+  });
+
+  it('rejects a subtype inversion — the core may never depend on an extension', () => {
+    const registry = createTokenRegistry();
+    registry.registerAll([token({ id: 'x-habits:mark', mode: 'signal', subtypeOf: 'signal:refresh', schema: z.object({}), sample: {} })], {
+      origin: 'staging',
+    });
+    const issues = registry.registerAll([token({ id: 'x-other:thing', subtypeOf: 'x-habits:mark' })], { origin: 'staging' });
+    expect(issues).toEqual([]); // extension → extension is fine
+
+    const inverted = new TokenRegistry([]);
+    inverted.registerAll([token({ id: 'x-habits:mark', mode: 'signal', schema: z.object({}), sample: {} })], { origin: 'staging' });
+    const coreIssues = inverted.registerAll([token({ id: 'media:videos', subtypeOf: 'x-habits:mark' })], { origin: 'base' });
+    expect(coreIssues.map((i) => i.code)).toEqual(['subtype-inversion']);
+  });
+
+  it('rejects an extension whose sample does not satisfy its own schema', () => {
+    const registry = createTokenRegistry();
+    const issues = registry.registerAll([token({ id: 'x-habits:bad', schema: z.object({ id: z.string() }), sample: { id: 7 } })], {
+      origin: 'staging',
+    });
+    expect(issues.map((i) => i.code)).toEqual(['token-sample-invalid']);
+  });
+
+  it('reports a missing supertype rather than registering a dangling edge', () => {
+    const registry = createTokenRegistry();
+    const issues = registry.registerAll([token({ id: 'x-habits:mark', subtypeOf: 'ghost:token' })], { origin: 'staging' });
+    expect(issues.map((i) => i.code)).toEqual(['token-supertype-missing']);
+    expect(registry.has('x-habits:mark')).toBe(false);
+  });
+
+  it('maps extension ids back to their plugin', () => {
+    expect(isExtensionTokenId('x-habits:mark')).toBe(true);
+    expect(isExtensionTokenId('media:videos')).toBe(false);
+    expect(stagingPluginOf('x-habits:mark')).toBe('plugin-habits');
+  });
+});
+
+describe('structural schema comparison (J4-D)', () => {
+  const shape = (schema: z.ZodType) => describeSchema(schema);
+
+  it('calls identical shapes identical', () => {
+    expect(compareSchemaShapes(shape(z.object({ id: z.string() })), shape(z.object({ id: z.string() })))).toBe('identical');
+  });
+
+  it('accepts an added optional field as backward compatible', () => {
+    expect(
+      compareSchemaShapes(shape(z.object({ id: z.string(), name: z.string().optional() })), shape(z.object({ id: z.string() }))),
+    ).toBe('backward-compatible-extension');
+  });
+
+  it('rejects an added REQUIRED field', () => {
+    expect(compareSchemaShapes(shape(z.object({ id: z.string(), name: z.string() })), shape(z.object({ id: z.string() })))).toBe('divergent');
+  });
+
+  it('rejects a producer that drops a field the consumer requires', () => {
+    expect(compareSchemaShapes(shape(z.object({ id: z.string() })), shape(z.object({ id: z.string(), name: z.string() })))).toBe('divergent');
+  });
+
+  it('recurses through arrays — the skew is never at the top level', () => {
+    const consumer = shape(z.object({ items: z.array(z.object({ id: z.string() })) }));
+    const extended = shape(z.object({ items: z.array(z.object({ id: z.string(), caption: z.string().optional() })) }));
+    const drifted = shape(z.object({ items: z.array(z.object({ id: z.number() })) }));
+    expect(compareSchemaShapes(extended, consumer)).toBe('backward-compatible-extension');
+    expect(compareSchemaShapes(drifted, consumer)).toBe('divergent');
+  });
+
+  it('treats a required→optional demotion of a consumer field as drift', () => {
+    const consumer = shape(z.object({ id: z.string() }));
+    const producer = shape(z.object({ id: z.string().optional() }));
+    expect(compareSchemaShapes(producer, consumer)).toBe('divergent');
+  });
+});