@peripheries/runtime 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @peripheries/runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contract between the host and federated component bundles
+([design/bundles.md](../../docs/plan/design/bundles.md) §6–7):
+
+- **`pinned`**: the shared specifiers bundles leave external (`react`,
+  `react/jsx-runtime`, `react-dom`, `zustand`, `@stack/store`, and the old
+  `@oa/store`), their pinned ranges and `/_shared/*.js` URLs, and the import map
+  the host serves (`/_shared/import-map.json` is the same payload).
+- **`contract`**: what a cell component receives (`CellProps`, `BaseProps`,
+  `DocumentCellProps`, `WriteResult`, `Size`, `CellContext`).
+- **`config`**: the cell, page and structure configuration shapes.
+- **`graph`**: `NodeRecord`, the state names, and the traversal configuration.
+
+Types and plain data only. It replaces the component repos' scripts that copy
+host files by relative path.
+
+**Publishing:** on npm as `@peripheries/runtime`, built output only, with
+`@peripheries/renderer` (`npm run publish:packages`; design/renderer.md §11).
+Version it with the host: a breaking change here is a breaking change for
+every bundle.

package/dist/index.js

@@ -0,0 +1,97 @@
+//#region packages/runtime/src/config.ts
+var SECTION_KINDS = [
+	"preamble",
+	"article",
+	"appendix",
+	"execution"
+];
+//#endregion
+//#region packages/runtime/src/graph.ts
+var STATE_TIERS = [
+	"meta",
+	"eng",
+	"ops"
+];
+var STATE_ROLES = [
+	"data",
+	"process",
+	"model",
+	"appraisal"
+];
+var STATE_NAMES = STATE_TIERS.flatMap((t) => STATE_ROLES.map((r) => `${t}_${r}`));
+var DEFAULT_STATE = "eng_data";
+var isStateName = (v) => typeof v === "string" && STATE_NAMES.includes(v);
+var WALK_DEFAULTS = {
+	direction: "incoming",
+	maxDepth: 3,
+	maxNodes: 50,
+	maxNodesCeiling: 500
+};
+//#endregion
+//#region packages/runtime/src/pinned.ts
+var STACK_RUNTIME_VERSION = "0.1.0";
+var RUNTIME_GLOBAL = "__STACK_RUNTIME__";
+var LEGACY_RUNTIME_GLOBAL = "__OA_RUNTIME";
+var READY_GLOBAL = "__STACK_RUNTIME_READY__";
+var RESOLVE_GLOBAL = "__STACK_RUNTIME_RESOLVE__";
+var PINNED_RUNTIMES = {
+	react: {
+		version: "^19.2.4",
+		url: "/_shared/react.js"
+	},
+	"react/jsx-runtime": {
+		version: "^19.2.4",
+		url: "/_shared/react-jsx-runtime.js"
+	},
+	"react/jsx-dev-runtime": {
+		version: "^19.2.4",
+		url: "/_shared/react-jsx-dev-runtime.js"
+	},
+	"react-dom": {
+		version: "^19.2.4",
+		url: "/_shared/react-dom.js"
+	},
+	"react-dom/client": {
+		version: "^19.2.4",
+		url: "/_shared/react-dom-client.js"
+	},
+	zustand: {
+		version: "^5.0.5",
+		url: "/_shared/zustand.js"
+	},
+	"@stack/store": {
+		version: "*",
+		url: "/_shared/stack-store.js"
+	}
+};
+var SPECIFIER_ALIASES = { "@oa/store": "@stack/store" };
+var HOST_INTERNAL_SHIMS = { "@stack/store": {
+	named: [
+		"useStore",
+		"useOAStore",
+		"getStore",
+		"selectors"
+	],
+	hasDefault: false
+} };
+function buildImportMap() {
+	const imports = {};
+	const pins = {};
+	for (const [specifier, pin] of Object.entries(PINNED_RUNTIMES)) {
+		imports[specifier] = pin.url;
+		pins[specifier] = pin.version;
+	}
+	for (const [alias, target] of Object.entries(SPECIFIER_ALIASES)) {
+		imports[alias] = PINNED_RUNTIMES[target].url;
+		pins[alias] = PINNED_RUNTIMES[target].version;
+	}
+	return {
+		version: STACK_RUNTIME_VERSION,
+		imports,
+		pins
+	};
+}
+//#endregion
+export { DEFAULT_STATE, HOST_INTERNAL_SHIMS, LEGACY_RUNTIME_GLOBAL, PINNED_RUNTIMES, READY_GLOBAL, RESOLVE_GLOBAL, RUNTIME_GLOBAL, SECTION_KINDS, SPECIFIER_ALIASES, STACK_RUNTIME_VERSION, STATE_NAMES, STATE_ROLES, STATE_TIERS, WALK_DEFAULTS, buildImportMap, isStateName };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/config.ts","../src/graph.ts","../src/pinned.ts"],"mappings":";AAyGA,IAAa,gBAAgB;CAAC;CAAY;CAAW;CAAY;AAAW;;;ACtG5E,IAAa,cAAc;CAAC;CAAQ;CAAO;AAAK;AAChD,IAAa,cAAc;CAAC;CAAQ;CAAW;CAAS;AAAW;AASnE,IAAa,cAAc,YAAY,SAAS,MAAM,YAAY,KAAK,MAAM,GAAG,EAAE,GAAG,GAAgB,CAAC;AACtG,IAAa,gBAA2B;AACxC,IAAa,eAAe,MAA+B,OAAO,MAAM,YAAa,YAAyB,SAAS,CAAC;AAiExH,IAAa,gBAAgB;CAAE,WAAW;CAAY,UAAU;CAAG,UAAU;CAAI,iBAAiB;AAAI;;;ACpEtG,IAAa,wBAAwB;AAGrC,IAAa,iBAAiB;AAC9B,IAAa,wBAAwB;AAErC,IAAa,eAAe;AAC5B,IAAa,iBAAiB;AAS9B,IAAa,kBAAkB;CAC7B,OAAO;EAAE,SAAS;EAAW,KAAK;CAAoB;CACtD,qBAAqB;EAAE,SAAS;EAAW,KAAK;CAAgC;CAChF,yBAAyB;EAAE,SAAS;EAAW,KAAK;CAAoC;CACxF,aAAa;EAAE,SAAS;EAAW,KAAK;CAAwB;CAChE,oBAAoB;EAAE,SAAS;EAAW,KAAK;CAA+B;CAC9E,SAAS;EAAE,SAAS;EAAU,KAAK;CAAsB;CAEzD,gBAAgB;EAAE,SAAS;EAAK,KAAK;CAA0B;AACjE;AAKA,IAAa,oBAAsD,EACjE,aAAa,eACf;AAMA,IAAa,sBAAmG,EAC9G,gBAAgB;CAAE,OAAO;EAAC;EAAY;EAAc;EAAY;CAAW;CAAG,YAAY;AAAM,EAClG;AAUA,SAAgB,iBAAmC;CACjD,MAAM,UAAkC,CAAC;CACzC,MAAM,OAA+B,CAAC;CACtC,KAAK,MAAM,CAAC,WAAW,QAAQ,OAAO,QAAQ,eAAe,GAAG;EAC9D,QAAQ,aAAa,IAAI;EACzB,KAAK,aAAa,IAAI;CACxB;CACA,KAAK,MAAM,CAAC,OAAO,WAAW,OAAO,QAAQ,iBAAiB,GAAG;EAC/D,QAAQ,SAAS,gBAAgB,OAAO,CAAC;EACzC,KAAK,SAAS,gBAAgB,OAAO,CAAC;CACxC;CACA,OAAO;EAAE,SAAS;EAAuB;EAAS;CAAK;AACzD"}

package/dist/types/config.d.ts

@@ -0,0 +1,126 @@
+import type { StateName, TraversalConfig } from './graph.js';
+/** A bundle reference: an org slug (its main lineage), a lineage, or a pinned bundle id. */
+export type BundleRef = string | {
+    bundle_id: string;
+} | {
+    bundle: string;
+    org_slug?: string;
+};
+export type ScopeKind = 'page' | 'project';
+/** A shared-store selection a cell reads, and writes when `writable`. */
+export interface SelectionDecl {
+    /** Channel shared by cells on the same scope. */
+    channel: string;
+    scope: ScopeKind;
+    /** Adds a `set<Name>` setter to the projection. */
+    writable?: boolean;
+    default?: unknown;
+    /** Mirror the value into a search param, so it survives refresh and sharing. */
+    url?: boolean;
+}
+export interface ViewStateDecl {
+    key: string;
+    scope: ScopeKind;
+    /** viewState is writable unless this is `false`. */
+    writable?: boolean;
+    default?: unknown;
+    url?: boolean;
+}
+export interface LiveDecl {
+    channel: string;
+    default?: unknown;
+}
+export type SelectionDeclarations = Record<string, SelectionDecl>;
+export type ViewStateDeclarations = Record<string, ViewStateDecl>;
+export type LiveDeclarations = Record<string, LiveDecl>;
+/**
+ * A declared producer: a node's newest state, optionally at a dot-path.
+ * `state` names the systems to read (default `eng_data`), merged in order,
+ * later winning; `system_id` names one system outright. `as: 'record'` binds
+ * the whole NodeRecord instead of the state's data (design/renderer.md §4.3).
+ */
+export type DeclaredBinding = {
+    graph_node_id: string;
+    system_id?: string;
+    field?: string;
+    state?: StateName | StateName[];
+    as?: 'value' | 'record';
+};
+export type ResponsiveBucket = 'narrow' | 'compact' | 'wide';
+export type CellLayout = {
+    span?: number;
+    order?: number;
+    className?: string;
+    sticky?: boolean;
+    zIndex?: number;
+    grid?: {
+        col?: string;
+        row?: string;
+    };
+    /** Each fires at or below its width: narrow 480, compact 720, wide 1024 (the page's width). */
+    hideWhen?: ResponsiveBucket;
+    showWhen?: ResponsiveBucket;
+    stackWhen?: ResponsiveBucket;
+    truncateWhen?: ResponsiveBucket;
+};
+export type CellData = {
+    static?: Record<string, unknown>;
+    queries?: Record<string, DeclaredBinding | {
+        registry: string;
+        params?: Record<string, unknown>;
+    }>;
+};
+/** The cell node that manages a cell's content: its newest `page_cell_config` in `system_id` (default the page's eng_data). */
+export type CellRef = {
+    graph_node_id: string;
+    system_id?: string;
+};
+/**
+ * A cell (design/renderer.md §3). Inline: the page holds its content. With a
+ * `ref`: the node manages its content and the page places it, and the inline
+ * fields are the fallback. Legacy forms are still read: `{ id, graph_node_id }`
+ * (a thin ref) as a ref, and an inline cell with a `graph_node_id` as inline,
+ * walking from that node.
+ */
+export type PageCell = {
+    id: string;
+    ref?: CellRef;
+    name?: string;
+    component?: string;
+    props?: Record<string, unknown>;
+    layout?: CellLayout;
+    conditions?: {
+        showIf?: unknown;
+        hideIf?: unknown;
+    };
+    children?: string[];
+    traversal?: TraversalConfig;
+    data?: CellData;
+    bundle_ref?: unknown;
+    actions?: Record<string, string>;
+    selections?: SelectionDeclarations;
+    viewState?: ViewStateDeclarations;
+    live?: LiveDeclarations;
+    metadata?: Record<string, unknown>;
+    graph_node_id?: string;
+};
+export declare const SECTION_KINDS: readonly ["preamble", "article", "appendix", "execution"];
+export type SectionKind = (typeof SECTION_KINDS)[number];
+/** A `layout.structure` node. A string is sugar for `{ cellId }`. */
+export type LayoutNode = {
+    cellId?: string;
+    children?: Array<LayoutNode | string>;
+    order?: number;
+    sectionId?: string;
+    documentId?: string;
+    title?: string;
+    level?: number;
+    tocHidden?: boolean;
+    kind?: SectionKind | string;
+    slot?: string;
+    print?: {
+        breakBefore?: boolean;
+        breakInside?: 'auto' | 'avoid';
+        keepWithPrevious?: boolean;
+    };
+};

package/dist/types/contract.d.ts

@@ -0,0 +1,112 @@
+import type { LiveDeclarations, SelectionDeclarations, ViewStateDeclarations } from './config.js';
+export interface UserContext {
+    id: string;
+    email: string;
+    fullName: string;
+}
+export interface TenantContext {
+    id: string;
+    orgSlug: string;
+    name: string;
+    /** Present when the rendering tenant is a client of an advisor org. */
+    advisorOrgSlug?: string;
+}
+/** Branding tokens: the org template's theme for the surface, camelCase and snake_case both present. */
+export interface ThemeConfig {
+    primaryColor: string;
+    secondaryColor: string;
+    logoUrl?: string;
+    [key: string]: unknown;
+}
+export interface BaseProps {
+    user: UserContext;
+    tenant: TenantContext;
+    theme: ThemeConfig;
+}
+export interface CellStatus {
+    isLoading: boolean;
+    isError: boolean;
+    errors?: Error[];
+}
+/** What an action returns. Actions never throw. */
+export interface WriteResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    id?: string;
+    errors?: Array<{
+        message: string;
+        field?: string;
+    }>;
+}
+export type CellAction<TInput = unknown, TResult = unknown> = (input: TInput) => Promise<WriteResult<TResult>>;
+/** Where the cell is: the same object an agent receives as its context. */
+export interface CellContext {
+    environment?: string;
+    orgId?: string | null;
+    clientId?: string | null;
+    projectId?: string | null;
+    processId?: string | null;
+    pageId?: string;
+    /** The cell's own graph node, when it has one. */
+    nodeId?: string;
+    [key: string]: unknown;
+}
+/** Projected shared-store values: each declared name, plus `set<Name>` where writable. */
+export type ProjectedStore = Record<string, unknown>;
+/** The measured container, for components whose contract declares `size: true`. */
+export interface Size {
+    width: number;
+    height: number;
+}
+/**
+ * Every prop the host passes a cell component, in addition to its own
+ * `cell.props` (resolved). Host-provided props win over authored ones of the
+ * same name, except `children`: child cells replace it only when there are some.
+ */
+export interface CellProps<TData extends Record<string, unknown> = Record<string, unknown>> {
+    baseProps: BaseProps;
+    children?: unknown;
+    isLoading: boolean;
+    error: Error | null;
+    data?: TData;
+    status?: CellStatus;
+    actions?: Record<string, CellAction>;
+    selections?: ProjectedStore;
+    viewState?: ProjectedStore;
+    live?: ProjectedStore;
+    size?: Size;
+    navigate: (to: string) => void;
+    /** The PWA's name for `navigate`. */
+    onNavigate: (to: string) => void;
+    context: CellContext;
+}
+/** On a document page, the whole document's facts, narrowed to the cell's own document. */
+export interface DocumentCellProps {
+    sectionNumbers: Record<string, number[]>;
+    sectionLevels: Record<string, number>;
+    sectionAuthoredLevels: Record<string, number>;
+    sectionTitles: Record<string, string>;
+    sectionAnchors: Record<string, string>;
+    sectionReferences: Record<string, SectionReference>;
+}
+export interface SectionReference {
+    number?: number[];
+    title?: string;
+    anchor?: string;
+    href?: string;
+    openable: boolean;
+    element?: {
+        index: number;
+        shape: ReadonlyArray<{
+            level?: number;
+            marker?: string;
+        }>;
+    };
+}
+/** Per component in a bundle's contracts.json. */
+export interface ComponentContract {
+    /** The host measures the container and passes `size`. */
+    size?: boolean;
+    [key: string]: unknown;
+}
+export type { LiveDeclarations, SelectionDeclarations, ViewStateDeclarations };

package/dist/types/graph.d.ts

@@ -0,0 +1,76 @@
+export declare const STATE_TIERS: readonly ["meta", "eng", "ops"];
+export declare const STATE_ROLES: readonly ["data", "process", "model", "appraisal"];
+export type StateTier = (typeof STATE_TIERS)[number];
+export type StateRole = (typeof STATE_ROLES)[number];
+/**
+ * A system, named for the `process.<tier>_<role>_system_id` column that holds
+ * it: `eng_data` is the engineering DSNS, `eng_process` its PSNS, and so on.
+ */
+export type StateName = `${StateTier}_${StateRole}`;
+export declare const STATE_NAMES: ("meta_data" | "meta_process" | "meta_model" | "meta_appraisal" | "eng_data" | "eng_process" | "eng_model" | "eng_appraisal" | "ops_data" | "ops_process" | "ops_model" | "ops_appraisal")[];
+export declare const DEFAULT_STATE: StateName;
+export declare const isStateName: (v: unknown) => v is StateName;
+/** A node's newest non-archived state in one system. */
+export interface StateRecord {
+    id: string;
+    system_id: string;
+    data: unknown;
+    status: string | null;
+    created_at: string;
+}
+export interface NodeRecord {
+    /** `node.id`: what `EdgeRecord.source` and `.target` name. */
+    id: string;
+    /** `graph_node.id`: what state rows and page cells name. */
+    graph_node_id: string;
+    name: string | null;
+    node_type: string | null;
+    status: string | null;
+    content: Record<string, unknown> | null;
+    metadata?: Record<string, unknown> | null;
+    /** `graph_node.rank`, the sibling order. */
+    rank: string | null;
+    updated_at: string | null;
+    /** Hops from the walk's start (walks only). */
+    depth?: number;
+    /** Only the systems asked for: absent when not asked, `null` when asked and the node has none. */
+    state: Partial<Record<StateName, StateRecord | null>>;
+}
+export interface EdgeRecord {
+    /** `graph_edge.id` */
+    id: string;
+    /** `edge.id` */
+    edge_id: string;
+    source: string;
+    target: string;
+    edge_type: string | null;
+    content?: unknown;
+}
+/** `@_traversal`: the cell's walk, without its start node and the page artifact. */
+export interface Traversal {
+    nodes: NodeRecord[];
+    edges: EdgeRecord[];
+}
+/** A cell's `traversal`: how its walk runs. */
+export interface TraversalConfig {
+    /** Default `incoming`: from the cell or page toward its producers. */
+    direction?: 'incoming' | 'outgoing' | 'both';
+    /** Required: the edge types the walk follows. */
+    edgeTypes: string[];
+    /** The walk enters only these types, so nothing past another type is reached. */
+    nodeTypes?: string[];
+    /** Default 3. */
+    maxDepth?: number;
+    /** Default 50, at most 500, the start included. */
+    maxNodes?: number;
+    /** The systems each reached node's state is read from. Default `['eng_data']`. */
+    include_state?: StateName[];
+    excludeNodeTypes?: string[];
+    excludeEdgeTypes?: string[];
+}
+export declare const WALK_DEFAULTS: {
+    readonly direction: "incoming";
+    readonly maxDepth: 3;
+    readonly maxNodes: 50;
+    readonly maxNodesCeiling: 500;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './config.js';
+export * from './contract.js';
+export * from './graph.js';
+export * from './pinned.js';

package/dist/types/pinned.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The shared runtime the host lends to federated bundles: one React, one
+ * ReactDOM, zustand, and the shared store. Single source of truth for the
+ * import map, the generated `/_shared/*.js` shims, and
+ * `/_shared/import-map.json`, which FEC repos' `validate-externals` reads to
+ * check their `external` list and peer ranges.
+ *
+ * Names are generic (design/bundles.md §6). The `@oa/*` specifier and the
+ * `__OA_RUNTIME` global stay as aliases until every FEC repo builds with the
+ * new names.
+ */
+export declare const STACK_RUNTIME_VERSION = "0.1.0";
+/** `globalThis[RUNTIME_GLOBAL][specifier]` is what each shim forwards. */
+export declare const RUNTIME_GLOBAL = "__STACK_RUNTIME__";
+export declare const LEGACY_RUNTIME_GLOBAL = "__OA_RUNTIME";
+/** A promise created by the boot script; resolved once the runtime is installed. */
+export declare const READY_GLOBAL = "__STACK_RUNTIME_READY__";
+export declare const RESOLVE_GLOBAL = "__STACK_RUNTIME_RESOLVE__";
+export type PinnedRuntime = {
+    /** Semver range a bundle's peerDependencies must satisfy. */
+    version: string;
+    /** URL the import map points the specifier at. */
+    url: string;
+};
+export declare const PINNED_RUNTIMES: {
+    readonly react: {
+        readonly version: "^19.2.4";
+        readonly url: "/_shared/react.js";
+    };
+    readonly 'react/jsx-runtime': {
+        readonly version: "^19.2.4";
+        readonly url: "/_shared/react-jsx-runtime.js";
+    };
+    readonly 'react/jsx-dev-runtime': {
+        readonly version: "^19.2.4";
+        readonly url: "/_shared/react-jsx-dev-runtime.js";
+    };
+    readonly 'react-dom': {
+        readonly version: "^19.2.4";
+        readonly url: "/_shared/react-dom.js";
+    };
+    readonly 'react-dom/client': {
+        readonly version: "^19.2.4";
+        readonly url: "/_shared/react-dom-client.js";
+    };
+    readonly zustand: {
+        readonly version: "^5.0.5";
+        readonly url: "/_shared/zustand.js";
+    };
+    readonly '@stack/store': {
+        readonly version: "*";
+        readonly url: "/_shared/stack-store.js";
+    };
+};
+export type RuntimeSpecifier = keyof typeof PINNED_RUNTIMES;
+/** Old specifier → the specifier it now resolves to. */
+export declare const SPECIFIER_ALIASES: Record<string, RuntimeSpecifier>;
+/**
+ * Specifiers with no installed package to introspect: their export surface is
+ * declared here and pinned by a test against the object the host installs.
+ */
+export declare const HOST_INTERNAL_SHIMS: Partial<Record<RuntimeSpecifier, {
+    named: string[];
+    hasDefault: boolean;
+}>>;
+export type ImportMapPayload = {
+    version: string;
+    imports: Record<string, string>;
+    /** Specifier → the semver range the host pins it to. */
+    pins: Record<string, string>;
+};
+/** The `<script type="importmap">` body, and the JSON FEC CI validates against. */
+export declare function buildImportMap(): ImportMapPayload;

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@peripheries/runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The host's runtime contract for federated component bundles: pinned shared specifiers, the import map, and the types of what a cell component receives.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peripheries-clients/peripheries-stack.git",
+    "directory": "packages/runtime"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}