@elaraai/east-ui 1.0.67 → 1.0.69

package/dist/src/collections/plan/ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../../../../src/collections/plan/ir.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EACH,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACb,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGhF,OAAO,EAMH,cAAc,EASjB,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,gBAAgB,CAAC,cAAc,EAAE,eAAe,CAA+C,CAAC;AAC7H,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsCvB,CAAC;AACH,2CAA2C;AAC3C,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC"}

package/dist/src/collections/plan/ir.js

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The Plan's resolved UIComponent-coupled IR — since the data-interface
+ * redesign only the ROOT and the review config touch `UIComponentType`; the
+ * whole row vocabulary (elements, kinds, rows, templates) is pure
+ * data in `./types.ts`. These are the named twins of the `Plan` arm in
+ * `component.ts` (which spells the SAME shapes inline with the recursion
+ * `node`). Keep the two in lockstep: every factory builds values of these
+ * types and `Plan.Root` constructs the variant against the arm, so any
+ * drift fails the specs at build time.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, FunctionType, NullType, OptionType, StringType, StructType, } from "@elaraai/east";
+import { UIComponentType } from "../../component.js";
+import { PickBindType } from "../../contracts/pick.js";
+import { reviewType } from "../../contracts/approval.js";
+import { CanDropFnType, DragEventType } from "../../contracts/drag.js";
+import { SliceChromeType } from "../../platform/slice/index.js";
+import { PlanAxisType, PlanGrainType, PlanLinkType, PlanRowsType, PlanElementRefType, PlanRowRefType, PlanRunClickEventType, PlanEventClickEventType, PlanMarkClickEventType, PlanChipClickEventType, PlanCellClickEventType, PlanGroupToggleEventType, PlanFooterItemType, PlanStyleType, } from "./types.js";
+// ============================================================================
+// Resolved types — the UIComponent-coupled shapes at `UIComponentType`
+// ============================================================================
+/**
+ * The Plan review config — the shared review contract at the Plan's
+ * keyed-row subject (`{ key }`).
+ */
+export const PlanReviewType = reviewType(PlanRowRefType, UIComponentType);
+/**
+ * The Plan root IR — the whole canvas.
+ *
+ * @remarks
+ * Window and resolution deliberately have **no callbacks**: they are slice
+ * writes (`setRange` / `setResolution`) — hosts observe the slice. Row
+ * order is data (no sort callback), and element detail lives in the root
+ * RESOLVERS: `popover` / `hover` over {@link PlanElementRefType} (a `none`
+ * result opens nothing) and `expandRender` over the row ref (the R2
+ * developer render for rows declaring `expand`) — one stored function per
+ * surface instead of UI embedded per element.
+ */
+export const PlanRootType = StructType({
+    rows: PlanRowsType,
+    // The link graph (R1) — run-edge to run-edge quantity links; the
+    // links-focus control gathers a row's transitive family over it.
+    links: ArrayType(PlanLinkType),
+    axis: PlanAxisType,
+    grain: OptionType(PlanGrainType),
+    // The generalized element resolvers (Plan Data Interface.md §3.3) —
+    // invoked lazily at interaction time; naming per the Schematic /
+    // Flowchart `*Hover` resolver convention (never `on*` — that prefix is
+    // the action callbacks below).
+    popover: OptionType(FunctionType([PlanElementRefType], OptionType(UIComponentType))),
+    hover: OptionType(FunctionType([PlanElementRefType], OptionType(UIComponentType))),
+    expandRender: OptionType(FunctionType([PlanRowRefType], UIComponentType)),
+    // The GUTTER half of R2. An expanded row's gutter cell grows with the row
+    // (one tall cell, top-aligned), and the space that opens up is the
+    // author's — identity that only earns its place when the row has the
+    // canvas. Same shape as `expandRender`, over the same row ref.
+    expandGutter: OptionType(FunctionType([PlanRowRefType], UIComponentType)),
+    review: OptionType(PlanReviewType),
+    pick: OptionType(PickBindType),
+    slice: OptionType(SliceChromeType),
+    footer: ArrayType(PlanFooterItemType),
+    // DnD target role — the shared grammar verbatim (contracts/drag.ts).
+    id: StringType,
+    sources: ArrayType(StringType),
+    onDrag: OptionType(FunctionType([DragEventType], NullType)),
+    canDrop: OptionType(CanDropFnType),
+    // Selection + per-element clicks.
+    onSelect: OptionType(FunctionType([PlanRowRefType], NullType)),
+    onRunClick: OptionType(FunctionType([PlanRunClickEventType], NullType)),
+    onEventClick: OptionType(FunctionType([PlanEventClickEventType], NullType)),
+    onMarkClick: OptionType(FunctionType([PlanMarkClickEventType], NullType)),
+    onChipClick: OptionType(FunctionType([PlanChipClickEventType], NullType)),
+    onCellClick: OptionType(FunctionType([PlanCellClickEventType], NullType)),
+    onGroupToggle: OptionType(FunctionType([PlanGroupToggleEventType], NullType)),
+    onGrainChange: OptionType(FunctionType([PlanGrainType], NullType)),
+    style: OptionType(PlanStyleType),
+});
+//# sourceMappingURL=ir.js.map

package/dist/src/collections/plan/ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.js","sourceRoot":"","sources":["../../../../src/collections/plan/ir.ts"],"names":[],"mappings":"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"}

package/dist/src/collections/plan/pick.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `Plan.pick` — the Plan's façade over the shared pick contract (#590).
+ *
+ * The contract holds identified things and does not know what they are, so an
+ * adopter supplies the two things it cannot: how to read identity off one item,
+ * and what a useful count is. For a Plan that is a nine-arm match over the
+ * series variant, plus the row count that series would contribute.
+ *
+ * Nothing here is Plan-specific machinery — it is ~40 lines of accessors. The
+ * façade exists so an author writes `Plan.pick(key, all)` instead of restating
+ * the match at every call site, not because the Plan needs its own contract.
+ *
+ * @packageDocumentation
+ */
+import { type ExprType, type SubtypeExprOrValue, ArrayType, DictType, StringType, StructType } from "@elaraai/east";
+import { type PickHandle, type PickItemType } from "../../contracts/pick.js";
+import { PlanSeriesType, type PlanSeriesInput } from "./series.js";
+/** Options for {@link createPlanPick}. */
+export interface PlanPickOptions {
+    /**
+     * The canvas data. Supplying it gives each library entry its row COUNT,
+     * derived by running that series' own pipeline — which is what turns "this
+     * series is on" into "this series contributes 18 rows", and what surfaces
+     * the `0 rs` case where a series is switched on to no visible effect.
+     *
+     * Omit it for a paged canvas: a window cannot know the total, and a wrong
+     * count is worse than none.
+     */
+    data?: SubtypeExprOrValue<DictType<StringType, StructType>>;
+    /** Series switched off to begin with; omit ⇒ everything shows. */
+    hidden?: readonly string[];
+}
+/**
+ * Bind a Plan's row series to a persisted pick.
+ *
+ * @remarks
+ * A GROUP is the unit a person picks — "add Machines" — and hiding one takes
+ * its whole subtree with it, because the members are built by the group's own
+ * `derive`. That is why every arm carries identity (#590 §6.1): without it the
+ * library could only offer top-level series, which on a grouped canvas is
+ * almost nothing.
+ *
+ * Identity is read through ONE nine-arm match rather than one match per
+ * accessor — every arm carries the same four fields, so matching four times
+ * would build four copies of the same traversal.
+ *
+ * @param key - The store key; also the persistence key
+ * @param all - Every series that COULD show
+ * @param options - Data for counts, and the initial hidden set ({@link PlanPickOptions})
+ * @returns A pick handle over the series type
+ *
+ * @example
+ * ```tsx
+ * const shown = $.let(Plan.pick("ops.series", all, { data: ops }));
+ *
+ * <Pick.Panel value={shown} title="Series" />
+ * <Plan axis={axis} data={ops} series={Pick.active(shown)} />
+ * ```
+ */
+export declare function createPlanPick(key: string, all: PlanSeriesInput, options?: PlanPickOptions): PickHandle<ReturnType<typeof PlanSeriesType>>;
+/**
+ * The library entries for a Plan's series — described, with NO state binding.
+ *
+ * @remarks
+ * {@link createPlanPick} builds its `items` from the same accessors, so proving
+ * this proves the bound path too. Split out because `State.bind` is not
+ * runnable in a `describeEast` spec (`TestImpl` carries no State runtime), and
+ * identity / kind icons / counts are exactly the part worth asserting.
+ *
+ * @param all - Every series that COULD show
+ * @param options - Data for counts ({@link PlanPickOptions})
+ * @returns One descriptor per series, in declaration order
+ */
+/**
+ * A stable signature of WHICH series a canvas is built from.
+ *
+ * @remarks
+ * Exists for the paged arm. `PagedSourceType` requires that "two sources with
+ * the same `id` must serve the same rows", and a derived source built from a
+ * SUBSET of the series serves different rows than one built from all of them —
+ * so its id has to say so.
+ *
+ * That requirement is not theoretical: the window cache invalidates on
+ * `source.id` alone (`use-plan-paging.ts`), and resident windows are immutable
+ * and served without re-calling `page`. Without a signature, toggling a series
+ * off leaves the previous rows on screen indefinitely
+ * (`use-plan-paging.dom.test.tsx` pins both halves of this).
+ *
+ * **This makes the key a load-bearing identity on a paged canvas.** The
+ * signature is the joined keys, so it assumes a key NAMES a series: same keys ⇒
+ * same rows. Two consequences worth knowing:
+ *
+ * - Two series sharing a key are safe HERE, because they share one entry in the
+ *   hidden set and so toggle together — the active list is both-in or both-out,
+ *   and the signature moves either way. They break the LIBRARY instead (one
+ *   switch, two labels — `Pick.Panel` reports it).
+ * - A key that stays put while the series it names CHANGES is the real hazard:
+ *   the id does not move, the cache is not dropped, and resident windows keep
+ *   serving rows built by the previous pipeline. Keys must be stable AND
+ *   identifying, which is what they were for.
+ *
+ * Row keys are a separate layer with its own rule: two series emitting the same
+ * ROW key resolve LAST_WINS inside `applySeries`, deterministically by series
+ * order, and identically in every window (#568).
+ *
+ * @param all - The series the canvas is built from
+ * @returns The series' keys, joined — stable for a given active set
+ */
+export declare function seriesSignature(all: PlanSeriesInput): ExprType<StringType>;
+export declare function createPlanPickItems(all: PlanSeriesInput, options?: PlanPickOptions): ExprType<ArrayType<PickItemType>>;
+//# sourceMappingURL=pick.d.ts.map

package/dist/src/collections/plan/pick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick.d.ts","sourceRoot":"","sources":["../../../../src/collections/plan/pick.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEH,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,SAAS,EACT,QAAQ,EAKR,UAAU,EACV,UAAU,EAGb,MAAM,eAAe,CAAC;AAGvB,OAAO,EAA6B,KAAK,UAAU,EAAE,KAAK,YAAY,EAAoB,MAAM,yBAAyB,CAAC;AAC1H,OAAO,EAAE,cAAc,EAAoB,KAAK,eAAe,EAAwB,MAAM,aAAa,CAAC;AAmC3G,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC5B;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;IAC5D,kEAAkE;IAClE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAyDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,eAAe,GAC1B,UAAU,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAM/C;AAED;;;;;;;;;;;;GAYG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,QAAQ,CAAC,UAAU,CAAC,CAa1E;AAED,wBAAgB,mBAAmB,CAC/B,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,eAAe,GAC1B,QAAQ,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAGnC"}

package/dist/src/collections/plan/pick.js

@@ -0,0 +1,193 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `Plan.pick` — the Plan's façade over the shared pick contract (#590).
+ *
+ * The contract holds identified things and does not know what they are, so an
+ * adopter supplies the two things it cannot: how to read identity off one item,
+ * and what a useful count is. For a Plan that is a nine-arm match over the
+ * series variant, plus the row count that series would contribute.
+ *
+ * Nothing here is Plan-specific machinery — it is ~40 lines of accessors. The
+ * façade exists so an author writes `Plan.pick(key, all)` instead of restating
+ * the match at every call site, not because the Plan needs its own contract.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, DictType, East, Expr, IntegerType, OptionType, StringType, StructType, some, none, } from "@elaraai/east";
+import { IconType } from "../../display/icon/types.js";
+import { createPickBind, pickItems } from "../../contracts/pick.js";
+import { PlanSeriesType, applySeriesValue } from "./series.js";
+/**
+ * The FA glyph each row kind declares.
+ *
+ * @remarks
+ * `PlanTemplateKindType` has documented this set since the template model, and
+ * nothing has ever rendered it — the library is the first surface that does.
+ * `group` and `rows` are not template kinds and so are not in that set; they
+ * take the marks that read as "a section" and "a hand-built list".
+ */
+const KIND_ICONS = {
+    span: "bars-staggered",
+    // `border-all` was a 2x2 grid of squares — the same mark `table-cells-large`
+    // draws for heat, and at 12px the two were indistinguishable (#590 §6.3).
+    // Buckets quantise into COLUMNS with lanes inside them, so a columns mark
+    // says what the row is and separates cleanly from heat's grid.
+    buckets: "table-columns",
+    chart: "chart-line",
+    heat: "table-cells-large",
+    table: "table-list",
+    cards: "user-group",
+    events: "flag",
+    group: "layer-group",
+    rows: "list",
+};
+/** Identity read off ONE series — the whole of what the library needs. */
+const PlanSeriesIdentityType = StructType({
+    key: StringType,
+    title: StringType,
+    subtitle: OptionType(StringType),
+    icon: OptionType(IconType),
+});
+/** The shared accessors — see {@link createPlanPick}. */
+function planPickOptions(allExpr, options) {
+    const itemType = Expr.type(allExpr).value;
+    /** One arm's identity, with the KIND's glyph when the series declares none. */
+    const ident = (v, tag) => East.value({
+        key: v["key"],
+        title: v["title"],
+        subtitle: v["subtitle"],
+        icon: v["icon"].match({
+            some: (_$, ic) => East.value(some(ic), OptionType(IconType)),
+            none: (_$) => East.value(some({ name: KIND_ICONS[tag], prefix: "fas", label: none, style: none }), OptionType(IconType)),
+        }),
+    }, PlanSeriesIdentityType);
+    // ONE reified match, CALLED by each accessor — every arm carries the same
+    // four fields, so matching per accessor would build four copies of the same
+    // traversal (`shared/reify.ts`: reify once, then call). The arms are spelled
+    // out rather than generated, mirroring `applySeriesValue` — an arm added to
+    // the variant should fail this match, not fall through a computed map.
+    const identityOf = East.function([itemType], PlanSeriesIdentityType, (_$, s) => s.match({
+        span: (_$2, v) => ident(v, "span"),
+        buckets: (_$2, v) => ident(v, "buckets"),
+        chart: (_$2, v) => ident(v, "chart"),
+        heat: (_$2, v) => ident(v, "heat"),
+        table: (_$2, v) => ident(v, "table"),
+        cards: (_$2, v) => ident(v, "cards"),
+        events: (_$2, v) => ident(v, "events"),
+        group: (_$2, v) => ident(v, "group"),
+        rows: (_$2, v) => ident(v, "rows"),
+    }));
+    // The row count this series contributes — its own pipeline, run over the
+    // canvas data. Absent for a paged canvas, which cannot know a total.
+    const data = options?.data;
+    const countOf = data === undefined ? undefined : East.function([itemType], IntegerType, (_$, s) => applySeriesValue(s, East.value(data)).size());
+    return {
+        id: (s) => identityOf(s).key,
+        title: (s) => identityOf(s).title,
+        subtitle: (s) => identityOf(s).subtitle,
+        icon: (s) => identityOf(s).icon,
+        ...(countOf !== undefined ? { count: (s) => some(countOf(s)) } : {}),
+        ...(options?.hidden !== undefined ? { hidden: options.hidden } : {}),
+    };
+}
+/**
+ * Bind a Plan's row series to a persisted pick.
+ *
+ * @remarks
+ * A GROUP is the unit a person picks — "add Machines" — and hiding one takes
+ * its whole subtree with it, because the members are built by the group's own
+ * `derive`. That is why every arm carries identity (#590 §6.1): without it the
+ * library could only offer top-level series, which on a grouped canvas is
+ * almost nothing.
+ *
+ * Identity is read through ONE nine-arm match rather than one match per
+ * accessor — every arm carries the same four fields, so matching four times
+ * would build four copies of the same traversal.
+ *
+ * @param key - The store key; also the persistence key
+ * @param all - Every series that COULD show
+ * @param options - Data for counts, and the initial hidden set ({@link PlanPickOptions})
+ * @returns A pick handle over the series type
+ *
+ * @example
+ * ```tsx
+ * const shown = $.let(Plan.pick("ops.series", all, { data: ops }));
+ *
+ * <Pick.Panel value={shown} title="Series" />
+ * <Plan axis={axis} data={ops} series={Pick.active(shown)} />
+ * ```
+ */
+export function createPlanPick(key, all, options) {
+    const allExpr = East.value(all);
+    // Typed at the SERIES shape, not the erased element type: that is what
+    // makes `Pick.active(shown)` assignable straight back to the `series` prop.
+    return createPickBind(key, allExpr, planPickOptions(allExpr, options));
+}
+/**
+ * The library entries for a Plan's series — described, with NO state binding.
+ *
+ * @remarks
+ * {@link createPlanPick} builds its `items` from the same accessors, so proving
+ * this proves the bound path too. Split out because `State.bind` is not
+ * runnable in a `describeEast` spec (`TestImpl` carries no State runtime), and
+ * identity / kind icons / counts are exactly the part worth asserting.
+ *
+ * @param all - Every series that COULD show
+ * @param options - Data for counts ({@link PlanPickOptions})
+ * @returns One descriptor per series, in declaration order
+ */
+/**
+ * A stable signature of WHICH series a canvas is built from.
+ *
+ * @remarks
+ * Exists for the paged arm. `PagedSourceType` requires that "two sources with
+ * the same `id` must serve the same rows", and a derived source built from a
+ * SUBSET of the series serves different rows than one built from all of them —
+ * so its id has to say so.
+ *
+ * That requirement is not theoretical: the window cache invalidates on
+ * `source.id` alone (`use-plan-paging.ts`), and resident windows are immutable
+ * and served without re-calling `page`. Without a signature, toggling a series
+ * off leaves the previous rows on screen indefinitely
+ * (`use-plan-paging.dom.test.tsx` pins both halves of this).
+ *
+ * **This makes the key a load-bearing identity on a paged canvas.** The
+ * signature is the joined keys, so it assumes a key NAMES a series: same keys ⇒
+ * same rows. Two consequences worth knowing:
+ *
+ * - Two series sharing a key are safe HERE, because they share one entry in the
+ *   hidden set and so toggle together — the active list is both-in or both-out,
+ *   and the signature moves either way. They break the LIBRARY instead (one
+ *   switch, two labels — `Pick.Panel` reports it).
+ * - A key that stays put while the series it names CHANGES is the real hazard:
+ *   the id does not move, the cache is not dropped, and resident windows keep
+ *   serving rows built by the previous pipeline. Keys must be stable AND
+ *   identifying, which is what they were for.
+ *
+ * Row keys are a separate layer with its own rule: two series emitting the same
+ * ROW key resolve LAST_WINS inside `applySeries`, deterministically by series
+ * order, and identically in every window (#568).
+ *
+ * @param all - The series the canvas is built from
+ * @returns The series' keys, joined — stable for a given active set
+ */
+export function seriesSignature(all) {
+    const allExpr = East.value(all);
+    const itemType = Expr.type(allExpr).value;
+    // An EMPTY series list has no element type (`Never`), so there is no
+    // variant to match on — and nothing to distinguish either. A canvas with no
+    // series is legal (`Plan.Root({ …, series: [] })`).
+    if (itemType.type !== "Variant")
+        return East.value("", StringType);
+    const keyOf = planPickOptions(allExpr).id;
+    const keyFn = East.function([itemType], StringType, (_$, s) => keyOf(s));
+    return allExpr.reduce((_$, acc, s) => East.str `${acc}/${keyFn(s)}`, East.value("", StringType));
+}
+export function createPlanPickItems(all, options) {
+    const allExpr = East.value(all);
+    return pickItems(allExpr, planPickOptions(allExpr, options));
+}
+//# sourceMappingURL=pick.js.map

package/dist/src/collections/plan/pick.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick.js","sourceRoot":"","sources":["../../../../src/collections/plan/pick.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAIH,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,IAAI,EACJ,IAAI,GACP,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAwD,MAAM,yBAAyB,CAAC;AAC1H,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAA8C,MAAM,aAAa,CAAC;AAE3G;;;;;;;;GAQG;AACH,MAAM,UAAU,GAA2B;IACvC,IAAI,EAAK,gBAAgB;IACzB,6EAA6E;IAC7E,0EAA0E;IAC1E,0EAA0E;IAC1E,+DAA+D;IAC/D,OAAO,EAAE,eAAe;IACxB,KAAK,EAAI,YAAY;IACrB,IAAI,EAAK,mBAAmB;IAC5B,KAAK,EAAI,YAAY;IACrB,KAAK,EAAI,YAAY;IACrB,MAAM,EAAG,MAAM;IACf,KAAK,EAAI,aAAa;IACtB,IAAI,EAAK,MAAM;CAClB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,sBAAsB,GAAG,UAAU,CAAC;IACtC,GAAG,EAAO,UAAU;IACpB,KAAK,EAAK,UAAU;IACpB,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC;IAChC,IAAI,EAAM,UAAU,CAAC,QAAQ,CAAC;CACjC,CAAC,CAAC;AAkBH,yDAAyD;AACzD,SAAS,eAAe,CACpB,OAAsC,EACtC,OAAyB;IAEzB,MAAM,QAAQ,GAAc,IAAI,CAAC,IAAI,CAAC,OAAO,CAAyB,CAAC,KAAK,CAAC;IAE7E,+EAA+E;IAC/E,MAAM,KAAK,GAAG,CAAC,CAAuB,EAAE,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC;QAC/D,GAAG,EAAO,CAAC,CAAC,KAAK,CAAmC;QACpD,KAAK,EAAK,CAAC,CAAC,OAAO,CAAmC;QACtD,QAAQ,EAAE,CAAC,CAAC,UAAU,CAA+C;QACrE,IAAI,EAAO,CAAC,CAAC,MAAM,CAAoC,CAAC,KAAK,CAAC;YAC1D,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;YAC5D,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CACpB,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,GAAG,CAAW,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAClF,UAAU,CAAC,QAAQ,CAAC,CAAC;SAC5B,CAAC;KACL,EAAE,sBAAsB,CAAC,CAAC;IAE3B,0EAA0E;IAC1E,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;IACvE,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,sBAAsB,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAC1E,CAAgC,CAAC,KAAK,CAAC;QACpC,IAAI,EAAK,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAoC,EAAE,MAAM,CAAC;QACxE,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAoC,EAAE,SAAS,CAAC;QAC3E,KAAK,EAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAoC,EAAE,OAAO,CAAC;QACzE,IAAI,EAAK,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAoC,EAAE,MAAM,CAAC;QACxE,KAAK,EAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAoC,EAAE,OAAO,CAAC;QACzE,KAAK,EAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAoC,EAAE,OAAO,CAAC;QACzE,MAAM,EAAG,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAoC,EAAE,QAAQ,CAAC;QAC1E,KAAK,EAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAoC,EAAE,OAAO,CAAC;QACzE,IAAI,EAAK,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAoC,EAAE,MAAM,CAAC;KAC3E,CAAU,CAAC,CAAC;IAEjB,yEAAyE;IACzE,qEAAqE;IACrE,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;IAC3B,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAC9F,gBAAgB,CAAC,CAA+B,EAC5C,IAAI,CAAC,KAAK,CAAC,IAAI,CAA+C,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAEhF,OAAO;QACH,EAAE,EAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG;QAClC,KAAK,EAAK,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK;QACpC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ;QACvC,IAAI,EAAM,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI;QACnC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAqB,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,cAAc,CAC1B,GAAW,EACX,GAAoB,EACpB,OAAyB;IAEzB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAA8C,CAAkC,CAAC;IAC5G,uEAAuE;IACvE,4EAA4E;IAC5E,OAAO,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CACpB,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,eAAe,CAAC,GAAoB;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAA8C,CAAkC,CAAC;IAC5G,MAAM,QAAQ,GAAc,IAAI,CAAC,IAAI,CAAC,OAAO,CAAyB,CAAC,KAAK,CAAC;IAC7E,qEAAqE;IACrE,4EAA4E;IAC5E,oDAAoD;IACpD,IAAK,QAA8B,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAC1F,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,OAAO,CAAC,MAAM,CACjB,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAA,GAAG,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,EAC5C,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,UAAU,CAAC,CACL,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAC/B,GAAoB,EACpB,OAAyB;IAEzB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAA8C,CAAkC,CAAC;IAC5G,OAAO,SAAS,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AACjE,CAAC"}

package/dist/src/collections/plan/root.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The Plan root — `Plan.Root`, which assembles the whole canvas value against
+ * the `component.ts` arm.
+ *
+ * @packageDocumentation
+ */
+import { type ExprType, type SubtypeExprOrValue, ArrayType, BooleanType, DictType, FunctionType, NullType, OptionType, StringType, StructType } from "@elaraai/east";
+import { UIComponentType } from "../../component.js";
+import { StatusValueType, type StatusValueLiteral } from "../../feedback/status/types.js";
+import { DensityType, type DensityLiteral } from "../../style/interaction.js";
+import { type ReviewConfig } from "../../contracts/review.js";
+import { DragEventType } from "../../contracts/drag.js";
+import { SliceBindType } from "../../platform/slice/index.js";
+import { type SliceAffordanceLiteral } from "../../contracts/slice-affordances.js";
+import { PlanGrainType, type PlanGrainLiteral, PlanLinkType, PlanRowRefType, PlanRunClickEventType, PlanEventClickEventType, PlanMarkClickEventType, PlanChipClickEventType, PlanCellClickEventType, PlanGroupToggleEventType, PlanElementRefType, type PlanAxisKindLiteral, type PlanAxisInput } from "./types.js";
+import { PlanSeriesType, type PlanSeriesInput } from "./series.js";
+import { type PickHandle } from "../../contracts/pick.js";
+import { type PagedSourceLike } from "../../contracts/source.js";
+/**
+ * The Plan review config — the shared {@link ReviewConfig} at the keyed-row
+ * subject (`{ key }`).
+ */
+export type PlanReviewConfig = ReviewConfig<PlanRowRefType>;
+/**
+ * Configuration for {@link Plan.Root} (the `<Plan>` tag's props).
+ *
+ * @remarks
+ * `K` is the canvas's axis kind, inferred from `axis` ALONE (`series` is a
+ * `NoInfer` site): a `Plan.axis.number(...)` fixes `K = "number"`, and every
+ * series in the array must then carry a kind within it — a `"time"` series
+ * is a compile error at the tag. An erased axis (a `$.let`-bound expression,
+ * a variant value) leaves `K` at every kind, so the render-time diagnostic
+ * decides; an erased series (`$.const`-bound list, East expression) is
+ * accepted on any axis for the same reason.
+ *
+ * @typeParam K - The canvas's axis kind — inferred from `axis`
+ * @property axis - The shared axis declaration (`Plan.axis` / `.time` / `.number` / `.ordinal`)
+ * @property rows - The canvas rows — kind-factory results (flattened subtrees); exclusive with `data`/`series`
+ * @property data - The raw data source (a `Dict<String, R>` value/expression, or a paged source of one); pairs with `series`
+ * @property series - The row series over `data` — `Plan.series.*` values (declared order resolves key collisions; rows sit in KEY order); exclusive with `pick`
+ * @property pick - A bound series library (`Plan.pick`) — the canvas shows the picked series and mounts the library panel; exclusive with `series`
+ * @property grain - Initial grain (`"group"` / `"resource"`; default resource)
+ * @property popover - Generalized click-popover resolver over the element ref (`none` result ⇒ no surface)
+ * @property hover - Generalized hovercard resolver over the element ref (`none` result ⇒ no surface)
+ * @property expandRender - The R2 developer render for rows declaring `expand` (called with the row ref)
+ * @property expandGutter - The R2 gutter render — fills the expanded row's grown gutter cell (called with the row ref)
+ * @property review - The shared review chrome (decision column + batch foot)
+ * @property slice - Bound slice chrome (toolbar affordances)
+ * @property footer - Status-footer items
+ * @property id - DnD target identity
+ * @property sources - Library ids accepted for `add` drags
+ * @property onDrag - The shared drag funnel (every drag kind)
+ * @property canDrop - IR-level drop veto (the ⊘ stage)
+ * @property onSelect - Row click (selection)
+ * @property onRunClick - Span bar click
+ * @property onEventClick - Bucket tile click
+ * @property onMarkClick - Event mark / decision diamond click
+ * @property onChipClick - Cards chip click
+ * @property onCellClick - Heat / table / weight / segment cell click
+ * @property onGroupToggle - Group strip ↔ rows toggle
+ * @property onGrainChange - Grain segment change
+ * @property style - Sizing, density and gutter width
+ */
+export interface PlanConfig<K extends PlanAxisKindLiteral = PlanAxisKindLiteral> {
+    /** The shared axis declaration (`Plan.axis` / `.time` / `.number` / `.ordinal`) — fixes the canvas kind `K`. */
+    axis: PlanAxisInput<K>;
+    /** The raw data source — a KEYED collection: a `Dict<String, R>` value or
+     *  expression (a `$.let`-bound map, `Data.bind(...).read()`) for the INLINE
+     *  arm, or a `$.let`-bound paged handle over one (`Data.bindPaged(ops)`)
+     *  for the PAGED arm; the East type is the discriminant.
+     *
+     *  The keys are load-bearing: a leaf row's key IS its data key, so the
+     *  canvas is ordered and addressed by the same keys the source is
+     *  (`datasetGetPage` windows and `datasetFindKey` searches that key order).
+     *  A positional collection is refused — key it at the call site with
+     *  `rows.toDict((_$, r) => r.id)`, which makes the choice explicit.
+     *
+     *  A PAGED canvas must also declare `axis.window` (or bind a slice range):
+     *  fitting the axis to whatever prefix has landed would re-fit it on every
+     *  window (#567 D8). */
+    data: SubtypeExprOrValue<DictType<StringType, StructType>> | PagedSourceLike;
+    /** The row series over `data` — `Plan.series.*` values, applied in DECLARED
+     *  order (a TS array or an East expression of
+     *  `ArrayType(Plan.Types.Series(R))`).
+     *
+     *  Declared order resolves KEY COLLISIONS only (last wins). It does NOT
+     *  set row order on screen: the canvas is one keyed collection
+     *  (`PlanRowsCollectionType` is a `Dict`, decoded as a `SortedMap`), so
+     *  rows sit in canonical KEY order however the series are listed. Order
+     *  rows by keying them for it — a `prefix` per series, or ordered data
+     *  keys (`"10-line1"`, `"20-line2"`).
+     *
+     *  Literal one-off chrome rides a `Plan.series.rows` entry.
+     *
+     *  Every series' axis kind must lie within the axis's (`K`): a `"time"`
+     *  series on a `"number"` axis fails to compile here. */
+    series?: PlanSeriesInput<NoInfer<K>>;
+    /**
+     * A bound series library from `Plan.pick` — the pickable form of `series`.
+     *
+     * @remarks
+     * Exclusive with `series`, because the handle already CARRIES the series
+     * list; passing both would say it twice and leave the two free to disagree.
+     * Give one or the other: `series` for a fixed canvas, `pick` for a canvas
+     * whose rows the user chooses.
+     *
+     * The Plan does the rest — it feeds itself the picked series and mounts the
+     * library panel as chrome, the way `slice` mounts the rail. Nothing is left
+     * for the author to wire, because a Plan already holds both things a pick
+     * needs: `series` IS the item list and `data` IS what the counts derive from.
+     *
+     * A pick is STATE, so a Plan carrying one must sit inside a `Reactive` —
+     * `Plan.pick` binds through `State.bind`, and a bind outside a reactive
+     * evaluation promotes the enclosing function to async.
+     */
+    pick?: PickHandle<ReturnType<typeof PlanSeriesType>>;
+    /** The link graph (R1) — run-edge quantity links (`Plan.link` values, map-derivable
+     *  from data); the links-focus control gathers a row's transitive family over it. */
+    links?: SubtypeExprOrValue<ArrayType<PlanLinkType>>;
+    /** Initial grain (default `"resource"`). */
+    grain?: PlanGrainLiteral | SubtypeExprOrValue<PlanGrainType>;
+    /** Generalized click-popover resolver — called with the clicked element's
+     *  ref (`run` / `event` / `chip` / `mark` / `cell` arm, each carrying the
+     *  row key); returning `none` opens no surface. */
+    popover?: SubtypeExprOrValue<FunctionType<[PlanElementRefType], OptionType<UIComponentType>>>;
+    /** Generalized hovercard resolver — the hover twin of `popover`. */
+    hover?: SubtypeExprOrValue<FunctionType<[PlanElementRefType], OptionType<UIComponentType>>>;
+    /** The R2 developer render — called with the row ref when a row declaring
+     *  `expand` focuses; builds the mounted body from captured data /
+     *  bind-handles. */
+    expandRender?: SubtypeExprOrValue<FunctionType<[PlanRowRefType], UIComponentType>>;
+    /** The R2 GUTTER render — an expanded row's gutter cell grows with the row
+     *  (one tall cell, top-aligned under the row's name), and this fills the
+     *  space that opens up: the identity, measures or controls that only earn
+     *  their place once the row has the canvas. Called with the same row ref
+     *  as `expandRender`. */
+    expandGutter?: SubtypeExprOrValue<FunctionType<[PlanRowRefType], UIComponentType>>;
+    /** The shared review chrome (decision column + batch foot); callbacks receive `{ key }`. */
+    review?: PlanReviewConfig;
+    /** Bound slice chrome — the handle + toolbar affordances (default `["cohort","filter","search","range","resolution","brush","summary"]`). */
+    slice?: {
+        /** The bound handle from `Slice.bind`. */
+        slice: SubtypeExprOrValue<SliceBindType>;
+        /** The toolbar affordances, in order. */
+        affordances?: SliceAffordanceLiteral[];
+    };
+    /** Status-footer items (`end: true` right-aligns). */
+    footer?: {
+        /** The footer text. */
+        text: SubtypeExprOrValue<StringType>;
+        /** Optional status tint. */
+        tone?: StatusValueLiteral | SubtypeExprOrValue<StatusValueType>;
+        /** Right-align the item. */
+        end?: boolean;
+    }[];
+    /** DnD target identity — names the Plan in drag-grammar cell refs. */
+    id?: string;
+    /** Library ids accepted for `add` drags (omit = no adds). */
+    sources?: string[];
+    /** The shared drag funnel — runs, chips, tiles, templates and reorders all report through it. */
+    onDrag?: SubtypeExprOrValue<FunctionType<[DragEventType], NullType>>;
+    /** IR-level drop veto — `false` ⇒ the ⊘ invalid stage; a throwing predicate fails open. */
+    canDrop?: SubtypeExprOrValue<FunctionType<[DragEventType], BooleanType>>;
+    /** Row click (selection). */
+    onSelect?: SubtypeExprOrValue<FunctionType<[PlanRowRefType], NullType>>;
+    /** Span bar click (`{ row, run }`). */
+    onRunClick?: SubtypeExprOrValue<FunctionType<[PlanRunClickEventType], NullType>>;
+    /** Bucket tile click (`{ row, event }`). */
+    onEventClick?: SubtypeExprOrValue<FunctionType<[PlanEventClickEventType], NullType>>;
+    /** Event mark / span decision-diamond click (`{ row, mark }`). */
+    onMarkClick?: SubtypeExprOrValue<FunctionType<[PlanMarkClickEventType], NullType>>;
+    /** Cards chip click (`{ row, chip }`). */
+    onChipClick?: SubtypeExprOrValue<FunctionType<[PlanChipClickEventType], NullType>>;
+    /** Bucket-cell click (`{ row, at }` — the bucket instant, not an index). */
+    onCellClick?: SubtypeExprOrValue<FunctionType<[PlanCellClickEventType], NullType>>;
+    /** Group strip ↔ rows toggle (fires after the in-place swap). */
+    onGroupToggle?: SubtypeExprOrValue<FunctionType<[PlanGroupToggleEventType], NullType>>;
+    /** Grain segment change (grain is Plan-local state; initial via `grain`). */
+    onGrainChange?: SubtypeExprOrValue<FunctionType<[PlanGrainType], NullType>>;
+    /** Sizing (#320), density, gutter width. */
+    style?: {
+        /** Definite height (`"fill"` fills the parent). */
+        height?: SubtypeExprOrValue<StringType>;
+        /** Max-height cap. */
+        maxHeight?: SubtypeExprOrValue<StringType>;
+        /** Row rhythm. */
+        density?: DensityLiteral | SubtypeExprOrValue<DensityType>;
+        /** Gutter width — a CSS px size (`"168px"`; default 168). */
+        gutterWidth?: SubtypeExprOrValue<StringType>;
+    };
+}
+/**
+ * Creates the Plan root — the whole canvas.
+ *
+ * @typeParam K - The canvas's axis kind, inferred from `config.axis`; every series must lie within it
+ * @param config - The Plan configuration ({@link PlanConfig})
+ * @returns An East expression of `UIComponentType`
+ *
+ * @remarks
+ * Window and resolution have no callbacks by design: they are slice writes
+ * (`setRange` / `setResolution`) — hosts observe the slice. Dragging a
+ * proposal is a Modify on its decision, not a free edit — host semantics
+ * behind `onDrag`; the surface only reports.
+ */
+export declare function createPlanRoot<K extends PlanAxisKindLiteral = PlanAxisKindLiteral>(config: PlanConfig<K>): ExprType<UIComponentType>;
+//# sourceMappingURL=root.d.ts.map

package/dist/src/collections/plan/root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../../../../src/collections/plan/root.ts"],"names":[],"mappings":"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"}