@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/recipes/kabuki-devtools/scene/scene.ts

@@ -0,0 +1,268 @@
+import type { ActorDefinition, Snapshot } from '@kestack/kabuki';
+import { beatsOf } from './beats.ts';
+import type { Beats, Said } from './beats.ts';
+import { layout } from './layout/index.ts';
+import type { Box, Branch, Kind } from './layout/index.ts';
+import type { ActorNode, Item } from './nodes.ts';
+import { treeOf } from './tree.ts';
+import type { Statuses } from './tree.ts';
+
+/*
+ * A Scene: everything the Map draws for one Step, placed. Pure.
+ *
+ * 1. Tree    the Nodes, from the Actors and the Step's Snapshot.
+ * 2. Layout  a packed tree or an outline. Under a card, one small node per
+ *            State that starts something: the State it is in holds what it
+ *            starts; any other only names it, faded. What runs in every
+ *            State hangs straight from the card. So a Transition moves the
+ *            Map, and so does a fold: a folded card hides what hangs below
+ *            it and names it, under itself.
+ * 3. Light   a Node is lit while an Instance runs there; a line while both
+ *            its ends are.
+ * 4. Beats   what the Step's Message did, if it has one.
+ */
+
+export type Placed = ActorNode &
+  Box & {
+    readonly lit: boolean;
+    /** Folded: what hangs right below it, by name, and how many places hide below in all. */
+    readonly folded?: {
+      readonly names: ReadonlyArray<string>;
+      readonly hidden: number;
+    };
+  };
+
+/** The room a folded card's names take under it. */
+export const FOLD = 30;
+
+/** A State node: one State of a card that starts something. */
+export interface PlacedState extends Box {
+  readonly id: string;
+  /** The card it belongs to. */
+  readonly owner: string;
+  readonly tag: string;
+  /** The card's Instance is in it, so what it starts runs. */
+  readonly active: boolean;
+  readonly lit: boolean;
+  /** Not the one it is in: what it would start, by name, under it. */
+  readonly names?: ReadonlyArray<string>;
+}
+
+/** A State node's height, and its room for names when it is not the one. */
+export const STATE = { height: 26, names: 22 } as const;
+
+const stateWidth = (tag: string) => Math.max(72, 34 + tag.length * 7);
+
+/** The ID of a card's State node. */
+export const stateId = (owner: string, tag: string) => `${owner}~${tag}`;
+
+/** The State a card's shown Instance is in. */
+const currentOf = (node: ActorNode) =>
+  (node.many ? node.chosen : node.instances[0])?.state._tag;
+
+export interface Scene {
+  readonly nodes: ReadonlyArray<Placed>;
+  readonly lines: ReadonlyArray<{
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    readonly d: string;
+    readonly lit: boolean;
+  }>;
+  readonly labels: ReadonlyArray<{
+    readonly id: string;
+    readonly owner: string;
+    readonly text: string;
+    readonly x: number;
+    readonly y: number;
+    readonly align: 'middle' | 'start';
+    readonly lit: boolean;
+  }>;
+  /** The State nodes. */
+  readonly states: ReadonlyArray<PlacedState>;
+  readonly beats: Beats | undefined;
+  /** Where every Node sits, by ID. */
+  readonly at: ReadonlyMap<string, Placed>;
+  /** The live app's Workers are laid over it. */
+  readonly live: boolean;
+}
+
+export interface Shown {
+  readonly definition: ActorDefinition;
+  readonly snapshot: Snapshot;
+  /** The Step's Message; none for init. */
+  readonly said?: Said;
+  /** What the live app says of each Instance's Workers; none away from it. */
+  readonly statuses?: Statuses;
+  readonly layout?: Kind;
+  /** The Instance chosen at each place of many, by the place's ID. */
+  readonly chosen?: ReadonlyMap<string, string>;
+  /** The cards folded, by ID. */
+  readonly folded?: ReadonlySet<string>;
+}
+
+const NOT_LIVE: Statuses = () => undefined;
+
+const branchOf = (
+  { node, children }: Item,
+  folded: ReadonlySet<string>,
+): Branch => {
+  if (folded.has(node.id) && children.length)
+    return {
+      id: node.id,
+      width: node.width,
+      height: node.height + FOLD,
+      children: [],
+    };
+  const current = currentOf(node);
+  // Children by the State that starts them, in the order the States are written.
+  const byState = new Map<string, Item[]>();
+  for (const { via, item } of children)
+    if (via) byState.set(via, [...(byState.get(via) ?? []), item]);
+  const states = [...byState].map(([tag, items]): { branch: Branch } => ({
+    branch:
+      tag === current
+        ? {
+            id: stateId(node.id, tag),
+            width: stateWidth(tag),
+            height: STATE.height,
+            children: items.map((item) => ({ branch: branchOf(item, folded) })),
+          }
+        : {
+            id: stateId(node.id, tag),
+            width: stateWidth(tag),
+            height: STATE.height + STATE.names,
+            children: [],
+          },
+  }));
+  return {
+    id: node.id,
+    width: node.width,
+    height: node.height,
+    children: [
+      ...states,
+      ...children
+        .filter(({ via }) => !via)
+        .map(({ item }) => ({ branch: branchOf(item, folded) })),
+    ],
+  };
+};
+
+/** How many places hang below an Item, at any depth. */
+const countBelow = (item: Item): number =>
+  item.children.reduce(
+    (sum, { item: child }) => sum + 1 + countBelow(child),
+    0,
+  );
+
+export const sceneOf = ({
+  definition,
+  snapshot,
+  said,
+  statuses,
+  layout: kind = 'tree',
+  chosen,
+  folded = new Set(),
+}: Shown): Scene => {
+  // 1. Tree
+  const toward = said
+    ? [
+        said.envelope.destination,
+        ...('instance' in said.envelope.source
+          ? [said.envelope.source.instance]
+          : []),
+      ]
+    : [];
+  const { tree, find } = treeOf(
+    definition,
+    snapshot,
+    statuses ?? NOT_LIVE,
+    chosen,
+    toward,
+  );
+  const nodes = new Map<string, ActorNode>();
+  const items = new Map<string, Item>();
+  const parents = new Map<string, string>();
+  const collect = (item: Item) => {
+    nodes.set(item.node.id, item.node);
+    items.set(item.node.id, item);
+    for (const { item: child } of item.children) {
+      parents.set(child.node.id, item.node.id);
+      collect(child);
+    }
+  };
+  collect(tree);
+
+  // 2. Layout
+  const laid = layout(branchOf(tree, folded), kind);
+
+  // 3. Light
+  const states: PlacedState[] = [];
+  for (const [id, box] of laid.boxes) {
+    if (nodes.has(id)) continue;
+    const owner = box.parent!;
+    const node = nodes.get(owner)!;
+    const tag = id.slice(owner.length + 1);
+    const active = currentOf(node) === tag;
+    states.push({
+      ...box,
+      id,
+      owner,
+      tag,
+      active,
+      lit: active && node.instances.length > 0,
+      ...(active
+        ? {}
+        : {
+            height: STATE.height,
+            names: items
+              .get(owner)!
+              .children.filter(({ via }) => via === tag)
+              .map(({ item }) => item.node.name),
+          }),
+    });
+  }
+  const placed: Placed[] = [...laid.boxes].flatMap(([id, box]) => {
+    if (!nodes.has(id)) return [];
+    const node = nodes.get(id)!;
+    const item = items.get(id)!;
+    const fold =
+      folded.has(id) && item.children.length
+        ? {
+            folded: {
+              names: item.children.map(({ item: child }) => child.node.name),
+              hidden: countBelow(item),
+            },
+            height: box.height - FOLD,
+          }
+        : {};
+    return [{ ...node, ...box, lit: node.instances.length > 0, ...fold }];
+  });
+  const at = new Map(placed.map((node) => [node.id, node]));
+  const stateAt = new Map(states.map((state) => [state.id, state]));
+  const lit = (id: string) => (at.get(id) ?? stateAt.get(id))!.lit;
+
+  return {
+    nodes: placed,
+    states,
+    lines: laid.lines.map((line) => ({
+      id: line.id,
+      from: line.from,
+      to: line.to,
+      d: line.d,
+      lit: lit(line.from) && lit(line.to),
+    })),
+    labels: [],
+    // 4. Beats
+    // A Message into a folded card's subtree beats at the folded card.
+    beats:
+      said &&
+      beatsOf(said, (id) => {
+        let place = find(id);
+        while (place && !at.has(place)) place = parents.get(place);
+        return place;
+      }),
+    at,
+    live: statuses !== undefined,
+  };
+};

package/src/recipes/kabuki-devtools/scene/tree.ts

@@ -0,0 +1,191 @@
+import { isMany } from '@kestack/kabuki';
+import type { ActorDefinition, Instance, Snapshot } from '@kestack/kabuki';
+import { measure } from './nodes.ts';
+import type { Item, WorkerKey, WorkerRow, WorkerStatus } from './nodes.ts';
+
+/*
+ * The Map's tree: its shape from the Actors alone, what runs in it from one
+ * Snapshot.
+ *
+ * One Node per place an Actor can run. Below it: the Children each of its
+ * States Invokes, marked with that State, then the Children written at its
+ * top. A dim Actor is drawn with everything below it, except an Actor
+ * already above it, so a tree of itself ends.
+ *
+ * Every Node holds every Instance at its place now: one for a fixed Child,
+ * any number for a slot of keyed Children. A slot of keyed Children shows
+ * one of them, the chosen one: its States count every Instance but mark the
+ * chosen one's, its Workers are the chosen one's, and only the chosen one's
+ * Children hang below it, so every place below holds at most what one
+ * Instance has. Unless another is chosen, it is the one on the way to the
+ * Step's Message, or the first.
+ *
+ * Every Instance and Worker key is found at the Node it is drawn on, and an
+ * Instance the Step stopped at its slot's Node, so a Message it Sent still
+ * has somewhere to start.
+ */
+
+/** What the live app says of an Instance's Workers; nothing away from it. */
+export type Statuses = (instance: string) =>
+  | ReadonlyArray<{
+      readonly name: string;
+      readonly key: string;
+      readonly status: Exclude<WorkerStatus, 'on'>;
+    }>
+  | undefined;
+
+const SINGLE = 'Single';
+
+const isStateless = (definition: ActorDefinition) =>
+  definition.states.length === 1 && definition.states[0] === SINGLE;
+
+/** An Instance ID without its key and how many times it was Invoked: its parent's ID and its slot. */
+const slotOf = (id: string) => id.replace(/(\[[^\]]*\])?#\d+$/, '');
+
+const asList = (
+  held: Instance | ReadonlyArray<Instance> | undefined,
+): ReadonlyArray<Instance> =>
+  held === undefined ? [] : isMany(held) ? held : [held];
+
+export const treeOf = (
+  root: ActorDefinition,
+  snapshot: Snapshot,
+  statuses: Statuses,
+  /** The Instance chosen at a place of many, by the place's ID. */
+  chosen: ReadonlyMap<string, string> = new Map(),
+  /** Instances to choose first, unless one is chosen: the Message's ends. */
+  toward: ReadonlyArray<string> = [],
+): {
+  readonly tree: Item;
+  /** The Node an Instance, or one of its Worker keys, is drawn on. */
+  readonly find: (id: string) => string | undefined;
+} => {
+  const drawnAt = new Map<string, string>();
+
+  /** One row per Worker the Actor has, each with the keys its Instances run now. */
+  const workers = (
+    definition: ActorDefinition,
+    instances: ReadonlyArray<Instance>,
+    owner: string,
+  ): ReadonlyArray<WorkerRow> =>
+    Object.entries(definition.workers).map(([name, worker]) => ({
+      name,
+      ...(worker.state === undefined ? {} : { state: worker.state }),
+      keys: instances.flatMap((instance) => {
+        if (worker.state !== undefined && worker.state !== instance.state._tag)
+          return [];
+        const live = statuses(instance.id);
+        const data = {
+          model: instance.model,
+          state: instance.state,
+          props: instance.props,
+        };
+        return worker.keys(data).map((key): WorkerKey => {
+          const id = `${instance.id}~${name}#${key}`;
+          drawnAt.set(id, owner);
+          return {
+            id,
+            key,
+            instance,
+            status: live
+              ? (live.find((each) => each.name === name && each.key === key)
+                  ?.status ?? 'running')
+              : 'on',
+          };
+        });
+      }),
+    }));
+
+  const actor = (
+    definition: ActorDefinition,
+    instances: ReadonlyArray<Instance>,
+    id: string,
+    many: boolean,
+    above: ReadonlySet<ActorDefinition>,
+  ): Item => {
+    for (const instance of instances) drawnAt.set(instance.id, id);
+    const stateless = isStateless(definition);
+    const pick = many
+      ? (instances.find((each) => each.id === chosen.get(id)) ??
+        instances.find((each) =>
+          toward.some((to) => to === each.id || to.startsWith(`${each.id}/`)),
+        ) ??
+        instances[0])
+      : undefined;
+    // What the card shows and what hangs below it: the chosen one's, at a place of many.
+    const shown = many ? (pick ? [pick] : []) : instances;
+    const size = measure(
+      definition.name,
+      many,
+      stateless ? undefined : definition.states,
+      Object.keys(definition.workers),
+    );
+    const count = (tag: string) =>
+      instances.filter((each) => each.state._tag === tag).length;
+    const node = {
+      id,
+      name: definition.name,
+      many,
+      instances,
+      ...(pick ? { chosen: pick } : {}),
+      ...(stateless
+        ? {}
+        : {
+            states: size.lines.map((line) =>
+              line.map((tag) => ({ tag, count: count(tag) })),
+            ),
+          }),
+      workers: workers(definition, shown, id),
+      width: size.width,
+      height: size.height,
+    };
+    // A dim Actor already above it would draw itself forever.
+    if (instances.length === 0 && above.has(definition))
+      return { node, children: [] };
+    const below = new Set(above).add(definition);
+
+    /** The slots written in one State, or at the top, held by `holders`. */
+    const slots = (
+      state: string,
+      lasting: boolean,
+      holders: ReadonlyArray<Instance>,
+    ) =>
+      Object.entries(definition.children[state] ?? {})
+        .filter(([name]) => definition.lasting.includes(name) === lasting)
+        .map(([name, held]) => {
+          const slot = `${id}>${name}`;
+          // An Instance this Step stopped is found at its slot.
+          for (const holder of instances)
+            drawnAt.set(`${holder.id}/${name}`, slot);
+          return actor(
+            held.definition,
+            holders.flatMap((holder) => asList(holder.children[name])),
+            slot,
+            held.many,
+            below,
+          );
+        });
+
+    const byState = stateless
+      ? slots(SINGLE, false, shown).map((item) => ({ item }))
+      : definition.states.flatMap((tag) =>
+          slots(
+            tag,
+            false,
+            shown.filter((each) => each.state._tag === tag),
+          ).map((item) => ({ via: tag, item })),
+        );
+    const lasting = slots(
+      stateless ? SINGLE : definition.states[0]!,
+      true,
+      shown,
+    ).map((item) => ({ item }));
+    return { node, children: [...byState, ...lasting] };
+  };
+
+  const tree = actor(root, [snapshot], root.name, false, new Set());
+  return {
+    tree,
+    find: (id) => drawnAt.get(id) ?? drawnAt.get(slotOf(id)),
+  };
+};

package/src/recipes/kabuki-devtools/sheet/index.ts

@@ -0,0 +1 @@
+export { Sheet } from './sheet.tsx';

package/src/recipes/kabuki-devtools/sheet/sheet.tsx

@@ -0,0 +1,193 @@
+import type { ReactNode } from 'react';
+import { motion, useReducedMotion } from 'motion/react';
+import { X } from 'lucide-react';
+import { cn } from '../../../components/lib/utils.ts';
+import { JsonTree } from '../../../components/viewers/json/index.ts';
+import { ink } from '../ink/index.ts';
+import type { Tone } from '../ink/index.ts';
+
+/*
+ * The Sheet: the data of what is picked, along the bottom of the Inspector.
+ *
+ * 1. Open   it grows up from the bottom, quickly, and shrinks away when
+ *           closed. Picking something else changes what it says in place:
+ *           it never closes and opens again.
+ * 2. Fit    on a wide Inspector it is a section of its own under the Map,
+ *           what is picked on its left and each value in a column beside
+ *           it; on a narrow one it is a drawer over the Map, the full width,
+ *           everything stacked.
+ * 3. Read   what it is and its name, a few facts, a list such as its
+ *           Workers, then each value as a tree.
+ */
+
+export interface SheetFact {
+  readonly label: string;
+  readonly value: ReactNode;
+}
+
+export interface SheetRow {
+  readonly label: string;
+  readonly detail: string;
+  readonly tone: Tone;
+}
+
+export interface SheetSection {
+  readonly title: string;
+  readonly value: unknown;
+}
+
+const OUT = [0.23, 1, 0.32, 1] as const;
+
+export function Sheet({
+  kind,
+  tone = 'lit',
+  title,
+  facts = [],
+  rows,
+  sections = [],
+  onClose,
+}: {
+  /** What is picked: an Instance, a State, a Worker, the Message. */
+  readonly kind: string;
+  readonly tone?: Tone;
+  readonly title: string;
+  readonly facts?: ReadonlyArray<SheetFact>;
+  /** A short list, such as Workers, with its title. */
+  readonly rows?: {
+    readonly title: string;
+    readonly items: ReadonlyArray<SheetRow>;
+  };
+  readonly sections?: ReadonlyArray<SheetSection>;
+  readonly onClose: () => void;
+}) {
+  const still = useReducedMotion();
+  return (
+    // 1. Open
+    <motion.section
+      aria-label={`${kind} ${title}`}
+      className={cn(
+        // 2. Fit: a drawer over the Map when narrow, a section under it when wide.
+        'bg-background absolute inset-x-0 bottom-0 z-30 flex max-h-[65%] flex-col overflow-hidden border-t @3xl:max-h-72',
+        'rounded-t-xl shadow-[0_-1px_2px_rgb(0_0_0/0.04),0_-8px_24px_rgb(0_0_0/0.08)]',
+        '@3xl:relative @3xl:z-auto @3xl:shrink-0 @3xl:rounded-none @3xl:shadow-none',
+      )}
+      initial={still ? false : { height: 0 }}
+      animate={{ height: 'auto' }}
+      exit={
+        still
+          ? { height: 0, transition: { duration: 0 } }
+          : { height: 0, transition: { duration: 0.12, ease: 'easeIn' } }
+      }
+      transition={{ duration: 0.18, ease: OUT }}
+    >
+      <div className="flex min-h-0 flex-1 flex-col">
+        {/* 3. Read: what it is */}
+        <header className="flex shrink-0 items-center gap-3 px-4 pt-3 pb-2">
+          <div className="min-w-0 flex-1">
+            <p
+              className="text-[10.5px] font-medium tracking-wider uppercase"
+              style={{ color: ink(tone) }}
+            >
+              {kind}
+            </p>
+            <h2 className="truncate text-sm font-semibold">{title}</h2>
+          </div>
+          <button
+            type="button"
+            aria-label="Close"
+            onClick={onClose}
+            className="text-muted-foreground hover:text-foreground hover:bg-muted grid size-8 shrink-0 place-items-center rounded-md transition-colors duration-150 outline-none focus-visible:ring-2 [&_svg]:size-4"
+          >
+            <X />
+          </button>
+        </header>
+
+        <div className="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto overscroll-contain px-4 pb-4 @3xl:flex-row @3xl:gap-6 @3xl:overflow-x-auto @3xl:overflow-y-hidden">
+          {(facts.length > 0 || rows) && (
+            <div className="flex shrink-0 flex-col gap-4 @3xl:w-64 @3xl:overflow-y-auto">
+              {facts.length > 0 && (
+                <dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5 text-xs">
+                  {facts.map((fact) => (
+                    <div key={fact.label} className="contents">
+                      <dt className="text-muted-foreground">{fact.label}</dt>
+                      <dd className="min-w-0 truncate font-mono text-[11.5px]">
+                        {fact.value}
+                      </dd>
+                    </div>
+                  ))}
+                </dl>
+              )}
+              {rows && (
+                <Part title={rows.title}>
+                  {rows.items.length === 0 ? (
+                    <p className="text-muted-foreground text-xs">
+                      None running.
+                    </p>
+                  ) : (
+                    <ul className="flex flex-col gap-1">
+                      {rows.items.map((row) => (
+                        <li
+                          key={row.label}
+                          className="flex items-center gap-2 text-xs"
+                        >
+                          <span
+                            className="size-1.5 shrink-0 rounded-full"
+                            style={{ backgroundColor: ink(row.tone) }}
+                          />
+                          <span className="min-w-0 flex-1 truncate font-mono text-[11.5px]">
+                            {row.label}
+                          </span>
+                          <span className="text-muted-foreground">
+                            {row.detail}
+                          </span>
+                        </li>
+                      ))}
+                    </ul>
+                  )}
+                </Part>
+              )}
+            </div>
+          )}
+
+          {/* 3. Read: each value */}
+          {sections.map((section) => (
+            <Part
+              key={section.title}
+              title={section.title}
+              className="@3xl:w-80 @3xl:shrink-0 @3xl:overflow-y-auto"
+            >
+              {section.value !== null && typeof section.value === 'object' ? (
+                <div className="bg-muted/40 rounded-lg border p-2">
+                  <JsonTree value={section.value} collapsed={2} tone="syntax" />
+                </div>
+              ) : (
+                <p className="font-mono text-xs">
+                  {JSON.stringify(section.value) ?? 'nothing'}
+                </p>
+              )}
+            </Part>
+          ))}
+        </div>
+      </div>
+    </motion.section>
+  );
+}
+
+function Part({
+  title,
+  className,
+  children,
+}: {
+  readonly title: string;
+  readonly className?: string;
+  readonly children: ReactNode;
+}) {
+  return (
+    <section className={cn('flex flex-col gap-1.5', className)}>
+      <h3 className="text-muted-foreground text-[10.5px] font-medium tracking-wider uppercase">
+        {title}
+      </h3>
+      {children}
+    </section>
+  );
+}

package/src/recipes/kabuki-devtools/timeline/index.ts

@@ -0,0 +1,2 @@
+export { Timeline } from './timeline.tsx';
+export type { TimelineBranch, TimelineStep } from './timeline.tsx';