cursedbelt 2.7.0 → 3.0.0

package/src/client/router/ccRouter.ts

@@ -1,197 +0,0 @@
-/**
- * The client SPA router (03 §5) — history-based, framework-agnostic core.
- *
- * The React binding lives in `cursedbelt/react`; the navigation state machine
- * lives here so it is testable without a DOM renderer and so the lifecycle
- * ordering law (03 §6.2) is enforced in one place rather than in a component's
- * effects.
- *
- * The ordering that matters: on navigate we **ensure the instance's lifecycle
- * has reached `ready` BEFORE the first view render**. `onReady` is where
- * instance-level port intake is registered, so rendering first would open a
- * window in which an emission lands with no intake and is lost — the
- * "signal-may-miss-premount" class V4 audits for statically.
- */
-import type { EffectiveManifest } from '../../verify/types';
-import { GO_ROUTE, type LocatorFailure, resolveLocator } from './locator';
-import { type CCRoute, matchRoute } from './routeTable';
-
-export interface CCRouteMatch {
-  route: CCRoute;
-  params: Record<string, string>;
-  path: string;
-}
-
-export type CCRouterState =
-  | { kind: 'match'; match: CCRouteMatch }
-  | { kind: 'fallback'; reason: LocatorFailure; locator?: string; path: string };
-
-export interface CCRouterOptions {
-  routes: readonly CCRoute[];
-  manifest: EffectiveManifest;
-  /** The authenticated tenant — required by every locator resolution (J3-2). */
-  tenantId: string;
-  /**
-   * Drive the instance to `ready` before the view renders. Resolves when
-   * `onLoad` → `onReady` have completed for that instance.
-   */
-  ensureInstanceReady?: (instanceId: string) => Promise<void>;
-  /** Called when the previous view leaves — aborts its view-scoped work. */
-  suspendInstance?: (instanceId: string) => void;
-  /** Injected for tests; defaults to `window.history` + `location`. */
-  history?: HistoryLike;
-}
-
-export interface HistoryLike {
-  readonly path: string;
-  push(path: string): void;
-  replace(path: string): void;
-  listen(onChange: (path: string) => void): () => void;
-}
-
-export interface CCRouter {
-  state(): CCRouterState;
-  navigate(path: string): Promise<void>;
-  /** Navigate by semantic locator (`cc://knowledge/note_102`). */
-  navigateToLocator(locator: string): Promise<void>;
-  subscribe(listener: (state: CCRouterState) => void): () => void;
-  /** Resolve the current URL. Call once at boot. */
-  start(): Promise<void>;
-  stop(): void;
-  /** Diagnostics raised during resolution (e.g. `ambiguous-deep-link`). */
-  warnings(): readonly string[];
-}
-
-const browserHistory = (): HistoryLike => ({
-  get path() {
-    return `${window.location.pathname}${window.location.search}`;
-  },
-  push: (path) => window.history.pushState({}, '', path),
-  replace: (path) => window.history.replaceState({}, '', path),
-  listen: (onChange) => {
-    const handler = () => onChange(`${window.location.pathname}${window.location.search}`);
-    window.addEventListener('popstate', handler);
-    return () => window.removeEventListener('popstate', handler);
-  },
-});
-
-export function createCcRouter(options: CCRouterOptions): CCRouter {
-  const history = options.history ?? browserHistory();
-  const listeners = new Set<(state: CCRouterState) => void>();
-  const warnings: string[] = [];
-
-  let state: CCRouterState = { kind: 'fallback', reason: 'unknown-route', path: history.path };
-  let currentInstanceId: string | null = null;
-  let unlisten: (() => void) | null = null;
-  /** Guards against an out-of-order resolution overwriting a newer navigation. */
-  let generation = 0;
-
-  const emit = (next: CCRouterState): void => {
-    state = next;
-    for (const listener of listeners) listener(next);
-  };
-
-  const resolve = async (path: string): Promise<void> => {
-    generation += 1;
-    const ticket = generation;
-
-    // `/go/:locator` — the external deep-link entry (03 §4).
-    const goPrefix = GO_ROUTE.slice(0, GO_ROUTE.indexOf(':'));
-    if (path.startsWith(goPrefix)) {
-      const locator = decodeURIComponent(path.slice(goPrefix.length).split('?')[0] ?? '');
-      await navigateToLocator(locator, true);
-      return;
-    }
-
-    const matched = matchRoute(options.routes, path.split('?')[0] ?? path);
-    if (!matched) {
-      emit({ kind: 'fallback', reason: 'unknown-route', path });
-      return;
-    }
-
-    if (matched.route.redirectTo !== undefined) {
-      // An alias forwards to its canonical path so the address bar and any
-      // subsequent share-link agree with the declared route.
-      const canonical = substitute(matched.route.redirectTo, matched.params);
-      history.replace(canonical);
-      await resolve(canonical);
-      return;
-    }
-
-    // Lifecycle before render (03 §6.2). A view that renders before `onReady`
-    // can miss an emission that arrives in the gap.
-    if (currentInstanceId !== null && currentInstanceId !== matched.route.instanceId)
-      options.suspendInstance?.(currentInstanceId);
-
-    await options.ensureInstanceReady?.(matched.route.instanceId);
-
-    // A newer navigation started while we awaited readiness — drop this result
-    // rather than rendering a view the user has already navigated away from.
-    if (ticket !== generation) return;
-
-    currentInstanceId = matched.route.instanceId;
-    emit({ kind: 'match', match: { route: matched.route, params: matched.params, path } });
-  };
-
-  const navigateToLocator = async (locator: string, replace = false): Promise<void> => {
-    const resolution = resolveLocator(locator, options.tenantId, {
-      manifest: options.manifest,
-      tenantId: options.tenantId,
-    });
-
-    if (!resolution.ok) {
-      emit({ kind: 'fallback', reason: resolution.reason, locator, path: history.path });
-      return;
-    }
-
-    if (resolution.ambiguous)
-      warnings.push(
-        `ambiguous-deep-link: '${locator}' matched several instances; resolved by declaration order to '${resolution.instanceId}'. Qualify it as cc://<engine>@${resolution.instanceId}/… to silence this.`,
-      );
-
-    if (replace) history.replace(resolution.path);
-    else history.push(resolution.path);
-    await resolve(resolution.path);
-  };
-
-  return {
-    state: () => state,
-
-    async navigate(path: string) {
-      history.push(path);
-      await resolve(path);
-    },
-
-    navigateToLocator: (locator: string) => navigateToLocator(locator),
-
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => listeners.delete(listener);
-    },
-
-    async start() {
-      unlisten = history.listen((path) => {
-        void resolve(path);
-      });
-      await resolve(history.path);
-    },
-
-    stop() {
-      unlisten?.();
-      unlisten = null;
-      listeners.clear();
-    },
-
-    warnings: () => warnings,
-  };
-}
-
-/** Re-apply matched params to a canonical template when redirecting from an alias. */
-function substitute(template: string, params: Record<string, string>): string {
-  return template
-    .split('/')
-    .map((segment) =>
-      segment.startsWith(':') ? encodeURIComponent(params[segment.slice(1)] ?? segment) : segment,
-    )
-    .join('/');
-}

package/src/client/router/clientRoutesModule.spec.ts

@@ -1,114 +0,0 @@
-/**
- * `generateClientRoutesModule` (02 §3) — the emitter that had zero callers and,
- * until now, zero tests.
- *
- * The property under test is not "it produces a string": it is that the emitted
- * module has the shape a BUNDLER can split. A route table assembled at boot with
- * dynamic specifiers type-checks, runs, and silently collapses every view into
- * the main chunk — which is how a "lazy" editor ends up costing every user its
- * ffmpeg payload. So the assertions are about literal `import()` specifiers, one
- * entry per declared route and alias, and a table that survives being parsed back.
- */
-import { describe, expect, it } from 'bun:test';
-import { verifyAppConfig } from '../../verify/pipeline';
-import type { EffectiveManifest } from '../../verify/types';
-import { buildClientRoutes, defaultViewModulePath, generateClientRoutesModule, matchRoute } from './routeTable';
-
-const CONFIG = {
-  configVersion: 1,
-  app: { id: 'routes-demo', title: 'Routes Demo' },
-  profile: 'local',
-  engines: ['asset', 'knowledge'],
-  instances: [
-    {
-      engine: 'asset',
-      id: 'gallery',
-      features: { gallery: true, video: true, hls: false },
-      routes: [
-        { path: '/gallery', view: 'gallery', aliases: ['/photos', '/pics'] },
-        { path: '/videos/:videoId', view: 'video-detail' },
-      ],
-    },
-    {
-      engine: 'knowledge',
-      id: 'notes',
-      features: { notes: true },
-      routes: [{ path: '/notes/:noteId', view: 'note' }],
-    },
-  ],
-};
-
-const compile = async (): Promise<EffectiveManifest> => {
-  const result = await verifyAppConfig({ config: CONFIG, moment: 'export', capabilities: { ffmpeg: true } });
-  if (!result.manifest) throw new Error(`fixture failed to compile: ${JSON.stringify(result.diagnostics)}`);
-  return result.manifest;
-};
-
-describe('generateClientRoutesModule', () => {
-  it('emits one entry per declared route AND per alias', async () => {
-    const module = generateClientRoutesModule(await compile(), defaultViewModulePath);
-    for (const path of ['/gallery', '/photos', '/pics', '/videos/:videoId', '/notes/:noteId'])
-      expect(module).toContain(`path: ${JSON.stringify(path)},`);
-    expect(module.match(/path: /g)?.length).toBe(5);
-  });
-
-  it('emits LITERAL import specifiers — the only shape a bundler can split', async () => {
-    const module = generateClientRoutesModule(await compile(), defaultViewModulePath);
-    expect(module).toContain(`load: () => import("./engines/asset/views/gallery"),`);
-    expect(module).toContain(`load: () => import("./engines/knowledge/views/note"),`);
-    // No dynamic specifier anywhere: `import(` is always followed by a string literal.
-    for (const match of module.matchAll(/import\((.)/g)) expect(match[1]).toBe('"');
-  });
-
-  it('marks aliases as redirects to their canonical path, and only aliases', async () => {
-    const module = generateClientRoutesModule(await compile(), defaultViewModulePath);
-    expect(module.match(/redirectTo: /g)?.length).toBe(2);
-    expect(module).toContain(`redirectTo: "/gallery",`);
-  });
-
-  it('carries the params of the path it emits, not of the canonical route', async () => {
-    const module = generateClientRoutesModule(await compile(), defaultViewModulePath);
-    expect(module).toContain(`params: ["videoId"],`);
-    expect(module).toContain(`params: ["noteId"],`);
-    expect(module).toContain(`params: [],`);
-  });
-
-  it('stamps the bundleKey so a stale generated table is visible in a diff', async () => {
-    const manifest = await compile();
-    expect(generateClientRoutesModule(manifest, defaultViewModulePath)).toContain(`bundleKey: ${manifest.bundleKey}`);
-  });
-
-  it('honors a custom view-module layout', async () => {
-    const module = generateClientRoutesModule(await compile(), (engine, view) => `cursedbelt-views/${engine}--${view}.tsx`);
-    expect(module).toContain(`import("cursedbelt-views/asset--gallery.tsx")`);
-    expect(module).not.toContain('./engines/');
-  });
-
-  it('agrees with buildClientRoutes — one declaration, one table', async () => {
-    const manifest = await compile();
-    const built = buildClientRoutes({ manifest, lazyView: () => async () => ({ default: null }) });
-    const module = generateClientRoutesModule(manifest, defaultViewModulePath);
-    expect(built.collisions).toEqual([]);
-    for (const route of built.routes) expect(module).toContain(`path: ${JSON.stringify(route.path)},`);
-    // …and the runtime matcher resolves what the generated table declares.
-    const match = matchRoute(built.routes, '/videos/v_42');
-    expect(match?.route.instanceId).toBe('gallery');
-    expect(match?.params).toEqual({ videoId: 'v_42' });
-  });
-
-  it('emits an empty table (not broken syntax) for a manifest with no routes', async () => {
-    const result = await verifyAppConfig({
-      config: {
-        configVersion: 1,
-        app: { id: 'no-routes', title: 'No Routes' },
-        profile: 'local',
-        engines: ['system'],
-        instances: [{ engine: 'system', id: 'utils', features: {} }],
-      },
-      moment: 'export',
-      capabilities: {},
-    });
-    const module = generateClientRoutesModule(result.manifest as EffectiveManifest, defaultViewModulePath);
-    expect(module).toContain('export const CLIENT_ROUTES: readonly CCRoute[] = [\n\n];');
-  });
-});

package/src/client/router/index.ts

@@ -1,45 +0,0 @@
-/**
- * The client half of the Dual-Layer Router (03 §3.1, §4, §5).
- *
- * Framework-agnostic on purpose: the navigation state machine and the locator
- * resolver are testable without a renderer, and the React binding
- * (`cursedbelt/react`) is a thin subscription on top.
- */
-export {
-  CC_SCHEME,
-  DEEP_LINK_ENTITY_PREFIXES,
-  entityPrefixOf,
-  fillRouteTemplate,
-  GO_ROUTE,
-  goHref,
-  type LocatorContext,
-  type LocatorFailure,
-  type LocatorResolution,
-  parseLocator,
-  type ParsedLocator,
-  registerDeepLinkPrefixes,
-  resolveLocator,
-  toLocator,
-} from './locator';
-
-export {
-  buildClientRoutes,
-  type BuildRoutesOptions,
-  type BuiltRoutes,
-  type CCRoute,
-  defaultViewModulePath,
-  generateClientRoutesModule,
-  matchRoute,
-  routeParams,
-  type ViewLoader,
-  type ViewModulePath,
-} from './routeTable';
-
-export {
-  type CCRouteMatch,
-  type CCRouter,
-  type CCRouterOptions,
-  type CCRouterState,
-  createCcRouter,
-  type HistoryLike,
-} from './ccRouter';

package/src/client/router/locator.ts

@@ -1,181 +0,0 @@
-/**
- * Universal navigation — tenant-verified semantic locators (03 §4).
- *
- * The scheme is `cc://<engine>/<entity-id>`, e.g. `cc://knowledge/note_102`. The
- * reason it exists at all: a config or wire payload that hardcodes
- * `/plugins/notes/102` breaks the moment an app customizes its routes, so
- * literal paths in config are a V1 error (`literal-route-in-config`) and this is
- * the sanctioned alternative.
- *
- * **`tenantId` is a mandatory parameter, not an option (J3-2).** Resolution by
- * id alone leaked entities across tenants: any caller who could name an id got a
- * route to it. Making the tenant a required positional argument means a call
- * site cannot forget it — omitting it is a type error, not a silent
- * cross-tenant read. The client-side check is a fast fail, not the boundary; the
- * server re-verifies on every request regardless (03 §2.3), and a foreign row
- * comes back as a typed 404 so existence is never disclosed.
- */
-import type { EngineId } from '../../config/appConfig';
-import type { EffectiveManifest } from '../../verify/types';
-
-export const CC_SCHEME = 'cc://';
-
-export interface ParsedLocator {
-  engine: string;
-  entityId: string;
-  /** Explicit instance qualifier from `cc://knowledge@chat-main/note_1`. */
-  instanceId?: string;
-}
-
-/** Why a locator did not resolve. Mirrors `CCRouteFallback`'s `reason`. */
-export type LocatorFailure = 'unknown-route' | 'entity-missing' | 'unauthorized';
-
-export type LocatorResolution =
-  | { ok: true; path: string; instanceId: string; view: string; ambiguous: boolean }
-  | { ok: false; reason: LocatorFailure };
-
-/**
- * Parse `cc://<engine>[@<instanceId>]/<entity-id>`.
- *
- * Returns null rather than throwing: an unparseable locator is user-supplied
- * data (it can arrive from an external deep link), so it belongs in the
- * fallback path, not in an exception.
- */
-export function parseLocator(locator: string): ParsedLocator | null {
-  if (!locator.startsWith(CC_SCHEME)) return null;
-  const rest = locator.slice(CC_SCHEME.length);
-  const slash = rest.indexOf('/');
-  if (slash <= 0) return null;
-
-  const authority = rest.slice(0, slash);
-  const entityId = rest.slice(slash + 1);
-  if (entityId.length === 0) return null;
-
-  const at = authority.indexOf('@');
-  return at === -1
-    ? { engine: authority, entityId }
-    : { engine: authority.slice(0, at), instanceId: authority.slice(at + 1), entityId };
-}
-
-/** `note_102` → `note`. The prefix is the entity type ids are minted with (01 §2). */
-export const entityPrefixOf = (entityId: string): string => {
-  const underscore = entityId.indexOf('_');
-  return underscore === -1 ? entityId : entityId.slice(0, underscore);
-};
-
-/** Substitute a route template's single param: `/chat/:conversationId` → `/chat/conv_9482`. */
-export function fillRouteTemplate(template: string, entityId: string): string {
-  return template
-    .split('/')
-    .map((segment) => (segment.startsWith(':') ? encodeURIComponent(entityId) : segment))
-    .join('/');
-}
-
-export interface LocatorContext {
-  manifest: EffectiveManifest;
-  /** The AUTHENTICATED tenant. Mandatory (J3-2) — never defaulted, never optional. */
-  tenantId: string;
-  /**
-   * Tenant of the target entity, when the caller already knows it (a wire
-   * payload carries it). Omitted means "not yet known" and the target view's
-   * own fetch performs the check under the caller's claims.
-   */
-  entityTenantId?: string;
-}
-
-/**
- * Resolve a locator to a concrete client path.
- *
- * `ambiguous: true` means several instances declared the same
- * `deepLinkEntity`; declaration order wins and the caller emits WARNING
- * `ambiguous-deep-link`. An explicit `cc://knowledge@chat-main/...` qualifier
- * silences it.
- */
-export function resolveLocator(locator: string, tenantId: string, context: LocatorContext): LocatorResolution {
-  if (context.tenantId !== tenantId)
-    // A caller passing a tenant that disagrees with its own context is either a
-    // bug or an escalation attempt; either way it must not resolve.
-    return { ok: false, reason: 'unauthorized' };
-
-  const parsed = parseLocator(locator);
-  if (!parsed) return { ok: false, reason: 'unknown-route' };
-
-  if (context.entityTenantId !== undefined && context.entityTenantId !== tenantId)
-    return { ok: false, reason: 'unauthorized' };
-
-  const prefix = entityPrefixOf(parsed.entityId);
-
-  // Candidates: instances of the named engine that declare a route whose
-  // `deepLinkEntity` token matches this entity's type, in declaration order.
-  const candidates = context.manifest.instances
-    .filter((instance) => instance.engine === (parsed.engine as EngineId))
-    .filter((instance) => parsed.instanceId === undefined || instance.id === parsed.instanceId)
-    .flatMap((instance) =>
-      instance.routes
-        .filter((route) => route.deepLinkEntity !== undefined && matchesEntity(route.deepLinkEntity, prefix))
-        .map((route) => ({ instance, route })),
-    );
-
-  if (candidates.length === 0) return { ok: false, reason: 'unknown-route' };
-
-  const [winner] = candidates;
-  if (!winner) return { ok: false, reason: 'unknown-route' };
-
-  return {
-    ok: true,
-    path: fillRouteTemplate(winner.route.path, parsed.entityId),
-    instanceId: winner.instance.id,
-    view: winner.route.view,
-    ambiguous: candidates.length > 1 && parsed.instanceId === undefined,
-  };
-}
-
-/**
- * Which id prefixes each deep-link token owns.
- *
- * This is an explicit table rather than a string heuristic on the token's local
- * name, because the minted prefixes are deliberately short forms — `bookmark`
- * ids are `bm_…`, `worklog` ids are `wl_…`, `article` ids are `art_…`
- * (cwip `ID_PREFIXES`). Deriving the prefix from the token name would resolve
- * `bm_1` to nothing and, worse, could resolve a near-miss to the WRONG route.
- * A missing entry here yields `unknown-route` and the fallback UI, which is the
- * correct failure: visible, and never a silent mis-navigation.
- */
-export const DEEP_LINK_ENTITY_PREFIXES: Readonly<Record<string, readonly string[]>> = {
-  'knowledge:note-ref': ['note'],
-  'knowledge:conversation-ref': ['conv'],
-  'knowledge:records': ['list', 'lrow'],
-  'media:video-ref': ['vid'],
-  'media:items': ['itm', 'file'],
-  'media:videos': ['vid'],
-  'media:photos': ['pho'],
-  'asset:file-ref': ['file'],
-};
-
-/** Extra token → prefix mappings, contributed by promoted staging modules. */
-const extraPrefixes = new Map<string, readonly string[]>();
-
-/**
- * Register a deep-link token's id prefixes. Promotion (02 §3.3) calls this when
- * a staging module's token becomes a core one.
- */
-export const registerDeepLinkPrefixes = (tokenId: string, prefixes: readonly string[]): void => {
-  extraPrefixes.set(tokenId, prefixes);
-};
-
-function matchesEntity(deepLinkEntity: string, prefix: string): boolean {
-  const owned = extraPrefixes.get(deepLinkEntity) ?? DEEP_LINK_ENTITY_PREFIXES[deepLinkEntity];
-  return owned?.includes(prefix) === true;
-}
-
-/** Build a locator — the only sanctioned way to mint one. */
-export const toLocator = (engine: string, entityId: string, instanceId?: string): string =>
-  `${CC_SCHEME}${engine}${instanceId ? `@${instanceId}` : ''}/${entityId}`;
-
-/**
- * The external deep-link entry path. `/go/:locator` decodes and forwards, so an
- * external tool can link into an app without knowing its route customizations.
- */
-export const GO_ROUTE = '/go/:locator';
-
-export const goHref = (locator: string): string => `/go/${encodeURIComponent(locator)}`;