@peripheries/runtime 0.1.0 → 0.3.0

package/README.md

@@ -11,8 +11,13 @@ The contract between the host and federated component bundles
   `DocumentCellProps`, `WriteResult`, `Size`, `CellContext`).
 - **`config`**: the cell, page and structure configuration shapes.
 - **`graph`**: `NodeRecord`, the state names, and the traversal configuration.
+- **`@peripheries/runtime/rank`** (its own entry): sibling order on
+  `graph_node.rank` (`compareRank`, `sortByRank`, `rankBetween`,
+  `initialRanks`, `rankAfterLast`, `minimalReRank`, `isValidRank`), over
+  `fractional-indexing`. For the host, scripts and the agency; components get
+  sorted data and don't import it.
 
-Types and plain data only. It replaces the component repos' scripts that copy
+The main entry is 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

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/config.ts","../src/graph.ts","../src/pinned.ts"],"mappings":";AA0GA,IAAa,gBAAgB;CAAC;CAAY;CAAW;CAAY;AAAW;;;ACvG5E,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/rank.js

@@ -0,0 +1,86 @@
+import { generateKeyBetween, generateNKeysBetween } from "fractional-indexing";
+//#region packages/runtime/src/rank.ts
+var RANK_COLUMN = "rank";
+function compareRank(a, b) {
+	const ra = a.rank ?? "";
+	const rb = b.rank ?? "";
+	if (!ra && rb) return 1;
+	if (ra && !rb) return -1;
+	if (ra !== rb) return ra < rb ? -1 : 1;
+	return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function sortByRank(items, read) {
+	return items.slice().sort((x, y) => compareRank(read(x), read(y)));
+}
+function rankBetween(before, after, opts = {}) {
+	const key = generateKeyBetween(before ?? null, after ?? null);
+	if (!opts.jitter) return key;
+	const jittered = key + "123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"[Math.floor(Math.random() * 61)];
+	return after && jittered >= after ? key : jittered;
+}
+function initialRanks(n) {
+	if (n <= 0) return [];
+	return generateNKeysBetween(null, null, n);
+}
+function rankAfterLast(existing) {
+	const keys = existing.filter((k) => !!k).sort();
+	return rankBetween(keys[keys.length - 1] ?? null, null);
+}
+function minimalReRank(orderedIds, currentRanks, opts = {}) {
+	const ranked = orderedIds.map((id) => ({
+		id,
+		rank: currentRanks[id] ?? null
+	}));
+	const n = ranked.length;
+	const best = new Array(n).fill(0);
+	const prev = new Array(n).fill(-1);
+	let bestEnd = -1;
+	for (let i = 0; i < n; i++) {
+		if (!ranked[i].rank) continue;
+		best[i] = 1;
+		for (let j = 0; j < i; j++) if (ranked[j].rank && ranked[j].rank < ranked[i].rank && best[j] + 1 > best[i]) {
+			best[i] = best[j] + 1;
+			prev[i] = j;
+		}
+		if (bestEnd === -1 || best[i] > best[bestEnd]) bestEnd = i;
+	}
+	const keep = new Set();
+	for (let i = bestEnd; i !== -1; i = prev[i]) keep.add(i);
+	const out = [];
+	const finalRanks = ranked.map((r, i) => keep.has(i) ? r.rank : null);
+	let i = 0;
+	while (i < n) {
+		if (keep.has(i)) {
+			i += 1;
+			continue;
+		}
+		let j = i;
+		while (j < n && !keep.has(j)) j += 1;
+		const before = i > 0 ? finalRanks[i - 1] : null;
+		const after = j < n ? finalRanks[j] : null;
+		const runLength = j - i;
+		const keys = runLength === 1 ? [rankBetween(before, after, opts)] : generateNKeysBetween(before, after, runLength);
+		for (let k = 0; k < runLength; k++) {
+			finalRanks[i + k] = keys[k];
+			out.push({
+				id: ranked[i + k].id,
+				rank: keys[k]
+			});
+		}
+		i = j;
+	}
+	return out;
+}
+function isValidRank(key) {
+	if (typeof key !== "string" || key.length === 0) return false;
+	try {
+		generateKeyBetween(key, null);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { RANK_COLUMN, compareRank, initialRanks, isValidRank, minimalReRank, rankAfterLast, rankBetween, sortByRank };
+
+//# sourceMappingURL=rank.js.map

package/dist/rank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank.js","names":[],"sources":["../src/rank.ts"],"mappings":";;AAwIA,IAAa,cAAc;AAY3B,SAAgB,YACd,GACA,GACQ;CACR,MAAM,KAAK,EAAE,QAAQ;CACrB,MAAM,KAAK,EAAE,QAAQ;CAGrB,IAAI,CAAC,MAAM,IAAI,OAAO;CACtB,IAAI,MAAM,CAAC,IAAI,OAAO;CACtB,IAAI,OAAO,IAAI,OAAO,KAAK,KAAK,KAAK;CACrC,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI;AAC9C;AAGA,SAAgB,WACd,OACA,MACK;CACL,OAAO,MAAM,MAAM,CAAC,CAAC,MAAM,GAAG,MAAM,YAAY,KAAK,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;AACnE;AAUA,SAAgB,YACd,QACA,OACA,OAA6B,CAAC,GACtB;CACR,MAAM,MAAM,mBAAmB,UAAU,MAAM,SAAS,IAAI;CAC5D,IAAI,CAAC,KAAK,QAAQ,OAAO;CAMzB,MAAM,WAAW,MADF,gEAAS,KAAK,MAAM,KAAK,OAAO,IAAI,EAAe;CAGlE,OAAO,SAAS,YAAY,QAAQ,MAAM;AAC5C;AAGA,SAAgB,aAAa,GAAqB;CAChD,IAAI,KAAK,GAAG,OAAO,CAAC;CACpB,OAAO,qBAAqB,MAAM,MAAM,CAAC;AAC3C;AAGA,SAAgB,cAAc,UAA4D;CACxF,MAAM,OAAO,SAAS,QAAQ,MAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK;CAC3D,OAAO,YAAY,KAAK,KAAK,SAAS,MAAM,MAAM,IAAI;AACxD;AAwBA,SAAgB,cACd,YACA,cACA,OAA6B,CAAC,GACZ;CAClB,MAAM,SAAS,WAAW,KAAK,QAAQ;EAAE;EAAI,MAAM,aAAa,OAAO;CAAK,EAAE;CAM9E,MAAM,IAAI,OAAO;CACjB,MAAM,OAAO,IAAI,MAAc,CAAC,CAAC,CAAC,KAAK,CAAC;CACxC,MAAM,OAAO,IAAI,MAAc,CAAC,CAAC,CAAC,KAAK,EAAE;CACzC,IAAI,UAAU;CAEd,KAAK,IAAI,IAAI,GAAG,IAAI,GAAG,KAAK;EAC1B,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM;EACrB,KAAK,KAAK;EACV,KAAK,IAAI,IAAI,GAAG,IAAI,GAAG,KAGrB,IAAI,OAAO,EAAE,CAAC,QAAQ,OAAO,EAAE,CAAC,OAAQ,OAAO,EAAE,CAAC,QAAS,KAAK,KAAK,IAAI,KAAK,IAAI;GAChF,KAAK,KAAK,KAAK,KAAK;GACpB,KAAK,KAAK;EACZ;EAEF,IAAI,YAAY,MAAM,KAAK,KAAK,KAAK,UAAU,UAAU;CAC3D;CAEA,MAAM,OAAO,IAAI,IAAY;CAC7B,KAAK,IAAI,IAAI,SAAS,MAAM,IAAI,IAAI,KAAK,IAAI,KAAK,IAAI,CAAC;CAKvD,MAAM,MAAwB,CAAC;CAC/B,MAAM,aAAmC,OAAO,KAAK,GAAG,MAAO,KAAK,IAAI,CAAC,IAAI,EAAE,OAAQ,IAAK;CAE5F,IAAI,IAAI;CACR,OAAO,IAAI,GAAG;EACZ,IAAI,KAAK,IAAI,CAAC,GAAG;GACf,KAAK;GACL;EACF;EACA,IAAI,IAAI;EACR,OAAO,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,GAAG,KAAK;EAEnC,MAAM,SAAS,IAAI,IAAI,WAAW,IAAI,KAAK;EAC3C,MAAM,QAAQ,IAAI,IAAI,WAAW,KAAK;EACtC,MAAM,YAAY,IAAI;EAEtB,MAAM,OACJ,cAAc,IACV,CAAC,YAAY,QAAQ,OAAO,IAAI,CAAC,IACjC,qBAAqB,QAAQ,OAAO,SAAS;EAEnD,KAAK,IAAI,IAAI,GAAG,IAAI,WAAW,KAAK;GAClC,WAAW,IAAI,KAAK,KAAK;GACzB,IAAI,KAAK;IAAE,IAAI,OAAO,IAAI,EAAE,CAAC;IAAI,MAAM,KAAK;GAAG,CAAC;EAClD;EACA,IAAI;CACN;CAEA,OAAO;AACT;AAeA,SAAgB,YAAY,KAA6B;CACvD,IAAI,OAAO,QAAQ,YAAY,IAAI,WAAW,GAAG,OAAO;CACxD,IAAI;EACF,mBAAmB,KAAK,IAAI;EAC5B,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/types/config.d.ts

@@ -97,7 +97,11 @@ export type PageCell = {
     traversal?: TraversalConfig;
     data?: CellData;
     bundle_ref?: unknown;
-    actions?: Record<string, string>;
+    /** name → the mutation it means: `'pages.update'`, or `{ registry, entityKey }`. */
+    actions?: Record<string, string | {
+        registry: string;
+        entityKey?: string;
+    }>;
     selections?: SelectionDeclarations;
     viewState?: ViewStateDeclarations;
     live?: LiveDeclarations;

package/dist/types/graph.d.ts

@@ -57,7 +57,7 @@ export interface TraversalConfig {
     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. */
+    /** The walk enters only these types, so nothing past another type is reached. Empty or absent: no filter. */
     nodeTypes?: string[];
     /** Default 3. */
     maxDepth?: number;

package/dist/types/rank.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Where a node's order among its siblings lives: the `graph_node.rank` column.
+ *
+ * ── Why the membership row ──────────────────────────────────────────────────
+ *
+ * Order is GRAPH-SCOPED, so it belongs on the row representing a node's membership in
+ * a graph — not on the node. `graph_node` has no unique constraint on `node` (just a
+ * PK on `id` and three FKs), so the schema deliberately permits one node in several
+ * graphs; were membership 1:1, `node` would carry `graph` directly and this table
+ * would not exist. It happens to be 1:1 today (5,901 nodes, zero in more than one
+ * graph) but only because `duplicate_graph` clones fresh `node` rows per graph — a
+ * consequence of the clone strategy, not an invariant. "Order within what?" has no
+ * answer on a `node` row.
+ *
+ * Every other candidate was considered and rejected:
+ *
+ *   `system_node_state` — a new     NULL on the next append. Nothing carries state
+ *   column or its existing          metadata forward; each writer builds its own, and
+ *   `metadata` jsonb                `insertNodeState` names exactly seven columns.
+ *                                   Measured on the worst node locally: 71 appends,
+ *                                   6 with metadata, 65 NULL, writers interleaved.
+ *   DSNS `data.rank`                Survives (writers spread `{ ...current }`), but
+ *                                   state is append-only, so every drag appends a row,
+ *                                   bumps the appraisal fingerprint, and tells the
+ *                                   controller an objective changed because somebody
+ *                                   reordered a list.
+ *   `node.metadata.rank`            Survives everything including the clone, but
+ *                                   asserts that order is a property of the node.
+ *   `graph_node.position.rank`      Free and already cloned, but `position` is
+ *                                   React-Flow canvas x/y. Nothing persists it today;
+ *                                   the moment something does it will write `{x, y}`
+ *                                   wholesale and silently delete every rank, with no
+ *                                   reason to suspect list order was in there.
+ *   `edge.metadata` / `graph_edge`  The purest model — order among a parent's children
+ *                                   is a property of that edge, and multi-parent is
+ *                                   permitted. But the WRONG GRANULARITY for these
+ *                                   lists: the backlog orders every feature in the
+ *                                   walk filtered by kind, not one release's children,
+ *                                   so two features under different releases would
+ *                                   hold keys in incomparable namespaces. Cells also
+ *                                   cannot read edge metadata today —
+ *                                   `p_include_edge_metadata` defaults false and the
+ *                                   host never passes it.
+ *
+ * One comparable namespace per graph, and each cell sorts within whatever filtered set
+ * it displays. If per-parent ordering is ever needed — an independently ordered
+ * "Scope" list on a release page — an edge-scoped key can be added alongside without
+ * migrating this one, because fractional keys only need to be comparable within the
+ * set being sorted.
+ *
+ * Rank is deliberately NOT state: nothing appraises it, nothing derives from it, no
+ * guard applies to it. It is presentation ordering on a mutable row.
+ */
+export declare const RANK_COLUMN = "rank";
+/**
+ * Compare two rank keys, falling back to the id.
+ *
+ * The tiebreaker is not decoration: two offline clients inserting at the same
+ * position produce the same key, and an unranked item has no key at all. Without a
+ * deterministic second term the list order flickers between renders.
+ *
+ * Deliberately `<` / `>` and NOT `localeCompare` — see the collation note above.
+ * A locale comparator would interleave case and scramble the order.
+ */
+export declare function compareRank(a: {
+    rank?: string | null;
+    id: string;
+}, b: {
+    rank?: string | null;
+    id: string;
+}): number;
+/** Sort into display order. Stable, and total even with missing or equal keys. */
+export declare function sortByRank<T>(items: readonly T[], read: (item: T) => {
+    rank?: string | null;
+    id: string;
+}): T[];
+/**
+ * A key strictly between two neighbours. Either side may be null for "the end".
+ *
+ * `jitter` appends a random low-order character instead of taking the exact
+ * midpoint, which slows key growth under repeated inserts into one gap and makes
+ * two concurrent inserts less likely to collide. Off by default: it lengthens every
+ * key by one character, which is the wrong trade for the common single-drag case.
+ */
+export declare function rankBetween(before: string | null | undefined, after: string | null | undefined, opts?: {
+    jitter?: boolean;
+}): string;
+/** `n` fresh keys for a sibling set that has none — the initial backfill. */
+export declare function initialRanks(n: number): string[];
+/** A key that appends after everything in `existing`. Use when creating a record. */
+export declare function rankAfterLast(existing: ReadonlyArray<string | null | undefined>): string;
+export interface RankAssignment {
+    id: string;
+    rank: string;
+}
+/**
+ * Given the order the user wants and the ranks that exist, return ONLY the items
+ * whose key has to change.
+ *
+ * This is what keeps a reorder to one write. The naive implementation reassigns
+ * every sibling — N state rows per drag, which is exactly what D3d forbids and
+ * would also bump N appraisal fingerprints for a cosmetic change.
+ *
+ * Minimal by construction: it keeps the longest subsequence of items whose current
+ * keys are ALREADY in the desired relative order, and re-keys only the rest,
+ * generating each run of changed items between the two kept anchors that bracket
+ * it. For a single drag that is exactly one item. Items with no key are always
+ * assigned, which is how the lazy first-reorder backfill happens.
+ *
+ * Equal keys count as out of order, so a collision from two offline clients heals
+ * on the next reorder rather than persisting as a flickering list.
+ */
+export declare function minimalReRank(orderedIds: readonly string[], currentRanks: Readonly<Record<string, string | null | undefined>>, opts?: {
+    jitter?: boolean;
+}): RankAssignment[];
+/**
+ * Is this a well-formed key? For validating one that arrived from outside the host.
+ *
+ * DELEGATES to the generator rather than re-checking the invariant, and that is the
+ * point. The obvious implementation — reject anything ending in the lowest
+ * character — is WRONG, and wrong in a way that passes casual review: the invariant
+ * applies to the FRACTIONAL part, but the first character is a length marker, so
+ * "a0" is integer 0 with no fraction and is perfectly valid, while "a10" is integer
+ * 1 with a redundant trailing-zero fraction and is not. Telling those apart means
+ * decoding the length marker — exactly the fiddly edge case that argues for using a
+ * tested generator instead of hand-rolling one. `generateKeyBetween` already runs
+ * the real validator on its inputs, so asking it is both shorter and correct.
+ */
+export declare function isValidRank(key: unknown): key is string;

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "@peripheries/runtime",
-  "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.",
+  "version": "0.3.0",
+  "description": "The host's runtime contract for federated component bundles: pinned shared specifiers, the import map, the types of what a cell component receives, and sibling order (`/rank`).",
   "type": "module",
   "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./rank": {
+      "types": "./dist/types/rank.d.ts",
+      "default": "./dist/rank.js"
     }
   },
   "files": [
     "dist",
     "README.md"
   ],
+  "dependencies": {
+    "fractional-indexing": "4.0.0"
+  },
   "license": "UNLICENSED",
   "repository": {
     "type": "git",