@kestack/web-platform 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,419 @@
+import { useMemo, useRef, useState } from 'react';
+import type { ComponentProps } from 'react';
+import { AnimatePresence } from 'motion/react';
+import { handle, isRestore } from '@kestack/kabuki';
+import type {
+  ActorDefinition,
+  Entry,
+  Instance,
+  Snapshot,
+} from '@kestack/kabuki';
+import type { AppRuntime } from '@kestack/kabuki/react';
+import { cn } from '#lib/utils';
+import { INK } from './ink/index.ts';
+import type { Tone } from './ink/index.ts';
+import { AppMap } from './map/index.ts';
+import type { Pick } from './map/index.ts';
+import { sceneOf } from './scene/index.ts';
+import type {
+  Kind,
+  Placed,
+  Said,
+  Scene,
+  WorkerKey,
+  WorkerStatus,
+} from './scene/index.ts';
+import { Sheet } from './sheet/index.ts';
+import { Timeline } from './timeline/index.ts';
+
+/*
+ * The Inspector: the Step shown, drawn as a Map, with the Sheet and the
+ * Timeline under it. It fills whatever holds it, and lays itself out by its
+ * own width, not the screen's.
+ *
+ * 1. Scene     the Map of the Step shown, from the Actors and its Snapshot,
+ *              with the live app's Workers laid over it when it is live.
+ * 2. Pick      a card, a State or Worker on it, one of its Instances, or the
+ *              Step's Message; a pick gone from the Step shown closes the
+ *              Sheet.
+ * 3. Sheet     what is picked, taken apart.
+ * 4. Timeline  which Step is shown, and whether it is live.
+ */
+
+type Statuses = NonNullable<Parameters<typeof sceneOf>[0]['statuses']>;
+
+/*
+ * The Kabuki devtools: the Inspector on a running app, from its
+ * runtime (`App.useRuntime()`). It fills whatever holds it.
+ *
+ * 1. Steps     init, then every entry on the Branch shown: the Head's, or
+ *              the one a Step shown from another Branch is on.
+ * 2. Step      the Step shown is the app's own: picking one on the Timeline
+ *              Time Travels the app, and going live comes back to the Head.
+ *              Its Snapshot is replayed from the History; the Commands its
+ *              Message asked for are worked out again from the Step before,
+ *              once each.
+ * 3. Workers   live and running, what each Instance's Workers are doing.
+ */
+export function KabukiDevtools({
+  runtime,
+  layout,
+  dotted,
+  className,
+}: {
+  /** The running app: `App.useRuntime()`. */
+  readonly runtime: AppRuntime;
+  /** How the Map is laid out: a packed tree, or an outline. */
+  readonly layout?: Kind;
+  /** Dots under the Map. On by default; off, a background given by `className` shows through. */
+  readonly dotted?: boolean;
+  /** Classes for its root, merged over its own: a see-through background over the app. */
+  readonly className?: string;
+}) {
+  const { history, branch, shown, running } = runtime;
+  const definition = history.actor.definition;
+
+  // 1. Steps
+  const steps =
+    typeof shown === 'number' && !branch.some((entry) => entry.id === shown)
+      ? history.branch(shown)
+      : branch;
+  const live = shown === null;
+  const at =
+    shown === null
+      ? steps.length
+      : shown === 'init'
+        ? 0
+        : steps.findIndex((entry) => entry.id === shown) + 1;
+  const entry = at === 0 ? undefined : steps[at - 1];
+
+  // 2. Step
+  // By the entry itself, not its id: ids start again in another runtime, or
+  // once the History is cleared.
+  const asked = useRef(new WeakMap<Entry, ReadonlyArray<unknown>>());
+  const commandsOf = (of: Entry) => {
+    const known = asked.current.get(of);
+    if (known) return known;
+    const commands = isRestore(of.message)
+      ? []
+      : handle(definition, history.snapshotAt(of.parent), of).commands;
+    asked.current.set(of, commands);
+    return commands;
+  };
+  const step = useMemo(
+    () => ({
+      snapshot: history.snapshotAt(entry?.id ?? null),
+      ...(entry
+        ? { said: { envelope: entry, commands: commandsOf(entry) } }
+        : {}),
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- an entry never changes once written.
+    [history, entry],
+  );
+
+  return (
+    <Inspector
+      definition={definition}
+      step={step}
+      {...(layout ? { layout } : {})}
+      {...(className ? { className } : {})}
+      {...(dotted === undefined ? {} : { dotted })}
+      // 3. Workers
+      {...(live && running ? { statuses: runtime.workers } : {})}
+      timeline={{
+        steps: [
+          { id: 'init', label: 'init' },
+          ...steps.map((each) => ({
+            id: `${each.id}`,
+            label: each.message._tag,
+          })),
+        ],
+        shown: at,
+        live,
+        onShow: (index) =>
+          runtime.show(index === 0 ? 'init' : steps[index - 1]!.id),
+        onLive: () => runtime.show(null),
+      }}
+    />
+  );
+}
+
+export function Inspector({
+  definition,
+  step,
+  statuses,
+  layout,
+  timeline,
+  dotted,
+  className,
+}: {
+  /** The root Actor's definition. */
+  readonly definition: ActorDefinition;
+  /** The Step shown: its Snapshot, and the Message that made it; none for init. */
+  readonly step: { readonly snapshot: Snapshot; readonly said?: Said };
+  /** What the live app says of each Instance's Workers, while the Step shown is live. */
+  readonly statuses?: Statuses;
+  /** How the Map is laid out: a packed tree, or an outline. */
+  readonly layout?: Kind;
+  readonly timeline: ComponentProps<typeof Timeline>;
+  /** Dots under the Map. On by default. */
+  readonly dotted?: boolean;
+  /** Classes for its root, merged over its own. */
+  readonly className?: string;
+}) {
+  const [picked, setPicked] = useState<Pick | undefined>(undefined);
+  const [chosen, setChosen] = useState<ReadonlyMap<string, string>>(
+    () => new Map(),
+  );
+  const [folded, setFolded] = useState<ReadonlySet<string>>(() => new Set());
+
+  // 1. Scene
+  const scene = useMemo(
+    () =>
+      sceneOf({
+        definition,
+        snapshot: step.snapshot,
+        ...(step.said ? { said: step.said } : {}),
+        ...(statuses ? { statuses } : {}),
+        ...(layout ? { layout } : {}),
+        chosen,
+        folded,
+      }),
+    [definition, step, statuses, layout, chosen, folded],
+  );
+
+  // 2. Pick and 3. Sheet
+  const sheet = picked && sheetOf(scene, picked);
+
+  return (
+    <div
+      className={cn(
+        '@container bg-background text-foreground relative flex h-full w-full flex-col overflow-clip',
+        className,
+      )}
+      style={INK}
+    >
+      <div className="relative flex min-h-0 flex-1 flex-col">
+        <div className="relative min-h-0 flex-1">
+          <AppMap
+            scene={scene}
+            {...(dotted === undefined ? {} : { dotted })}
+            picked={sheet ? picked : undefined}
+            onPick={setPicked}
+            onChoose={(place, instance) =>
+              setChosen((was) => new Map(was).set(place, instance))
+            }
+            onFold={(place) =>
+              setFolded((was) => {
+                const next = new Set(was);
+                if (!next.delete(place)) next.add(place);
+                return next;
+              })
+            }
+          />
+        </div>
+        <AnimatePresence>
+          {sheet && (
+            <Sheet
+              key="sheet"
+              {...sheet}
+              onClose={() => setPicked(undefined)}
+            />
+          )}
+        </AnimatePresence>
+      </div>
+      {/* 4. Timeline */}
+      <Timeline {...timeline} />
+    </div>
+  );
+}
+
+type SheetOf = Omit<ComponentProps<typeof Sheet>, 'onClose'>;
+
+const dataOf = ({ _tag, ...data }: { readonly _tag: string }) => data;
+const hasFields = (value: object) => Object.keys(value).length > 0;
+const isEmpty = (value: unknown) =>
+  value !== null && typeof value === 'object' && !hasFields(value);
+
+const TONE: Record<WorkerStatus, Tone> = {
+  running: 'running',
+  finished: 'dim',
+  failed: 'failed',
+  on: 'lit',
+};
+
+const keyName = (name: string, key: WorkerKey) =>
+  key.key === '' ? name : `${name}#${key.key}`;
+
+/** Who Sent the Message, in words. */
+const fromOf = ({ source, send }: NonNullable<Scene['beats']>) => {
+  switch (source.kind) {
+    case 'view':
+      return 'its View';
+    case 'command':
+      return `Command ${send?.by ?? source.name}`;
+    case 'worker':
+      return `Worker ${send?.by ?? source.name}`;
+    case 'provide':
+      return 'what it Provides';
+    case 'outside':
+      return 'outside the app';
+    case 'restore':
+      return 'a Restore';
+  }
+};
+
+/** What the Sheet shows of a pick, or nothing if it is not in this Step. */
+const sheetOf = (scene: Scene, pick: Pick): SheetOf | undefined => {
+  if ('message' in pick) {
+    const beats = scene.beats;
+    if (!beats) return undefined;
+    return {
+      kind: 'Message',
+      tone: 'message',
+      title: beats.tag,
+      facts: [
+        {
+          label: 'To',
+          value: beats.to ? scene.at.get(beats.to)!.name : 'dropped',
+        },
+        { label: 'From', value: fromOf(beats) },
+        { label: 'Time', value: `${(beats.at / 1000).toFixed(2)}s` },
+      ],
+      sections: [
+        { title: 'Payload', value: beats.payload },
+        ...(beats.commands.length
+          ? [{ title: 'Commands asked for', value: beats.commands }]
+          : []),
+      ],
+    };
+  }
+
+  const node = scene.at.get(pick.node);
+  if (!node) return undefined;
+  const { part } = pick;
+  if (part && 'worker' in part)
+    return workerSheet(node, part.worker, scene.live);
+  if (part && 'state' in part) return stateSheet(node, part.state);
+
+  const one =
+    pick.instance !== undefined
+      ? node.instances.find((each) => each.id === pick.instance)
+      : !node.many
+        ? node.instances[0]
+        : undefined;
+  if (one) return instanceSheet(node.name, one);
+  if (node.instances.length === 0)
+    return {
+      kind: 'Actor',
+      tone: 'dim',
+      title: node.name,
+      facts: [{ label: 'Running', value: 'no Instance here at this Step' }],
+    };
+  return {
+    kind: 'Actor',
+    title: node.name,
+    facts: [
+      { label: 'Instances', value: node.instances.length },
+      ...(node.states
+        ? [
+            {
+              label: 'In each State',
+              value: node.states
+                .flat()
+                .map((option) => `${option.tag} ${option.count}`)
+                .join(' · '),
+            },
+          ]
+        : []),
+    ],
+  };
+};
+
+/** One Instance taken apart. */
+const instanceSheet = (name: string, instance: Instance): SheetOf => {
+  const state = dataOf(instance.state);
+  return {
+    kind: 'Instance',
+    title: instance.key === undefined ? name : `${name}#${instance.key}`,
+    facts: [
+      { label: 'ID', value: instance.id },
+      ...(instance.state._tag === 'Single'
+        ? []
+        : [{ label: 'State', value: instance.state._tag }]),
+      ...(instance.key === undefined
+        ? []
+        : [{ label: 'Key', value: instance.key }]),
+    ],
+    sections: [
+      ...(isEmpty(instance.model)
+        ? []
+        : [{ title: 'Model', value: instance.model }]),
+      ...(hasFields(state)
+        ? [{ title: `State ${instance.state._tag}`, value: state }]
+        : []),
+      ...(instance.props === undefined
+        ? []
+        : [{ title: 'Props', value: instance.props }]),
+    ],
+  };
+};
+
+/** One State of a card: which Instances are in it, and its data if one is. */
+const stateSheet = (node: Placed, tag: string): SheetOf => {
+  const inIt = node.instances.filter((each) => each.state._tag === tag);
+  const data = !node.many && inIt[0] ? dataOf(inIt[0].state) : {};
+  return {
+    kind: 'State',
+    tone: inIt.length ? 'active' : 'dim',
+    title: tag,
+    facts: [
+      { label: 'Of', value: node.name },
+      node.many
+        ? { label: 'Instances in it', value: inIt.length }
+        : {
+            label: 'Active',
+            value: inIt.length
+              ? 'yes'
+              : node.instances[0]
+                ? `no, it is in ${node.instances[0].state._tag}`
+                : 'not running at this Step',
+          },
+    ],
+    sections: hasFields(data) ? [{ title: 'Data', value: data }] : [],
+  };
+};
+
+/** One Worker of a card: where it is written, and each key it runs now. */
+const workerSheet = (node: Placed, name: string, live: boolean): SheetOf => {
+  const row = node.workers.find((each) => each.name === name);
+  const keys = row?.keys ?? [];
+  return {
+    kind: 'Worker',
+    tone: keys.some((each) => each.status === 'failed')
+      ? 'failed'
+      : keys.length
+        ? 'running'
+        : 'dim',
+    title: name,
+    facts: [
+      { label: 'Of', value: node.name },
+      {
+        label: 'Written',
+        value: row?.state ? `in ${row.state}` : 'at its top',
+      },
+      { label: 'Keys on', value: keys.length || 'none' },
+    ],
+    rows: {
+      title: live ? 'Keys, live' : 'Keys on at this Step',
+      items: keys.map((key) => ({
+        label:
+          key.instance.key === undefined
+            ? keyName(name, key)
+            : `${keyName(name, key)} · ${key.instance.key}`,
+        detail: key.status,
+        tone: TONE[key.status],
+      })),
+    },
+  };
+};

package/src/recipes/kabuki-devtools/map/beat/beat.tsx

@@ -0,0 +1,243 @@
+import { motion, useReducedMotion } from 'motion/react';
+import { ArrowUpRight, Zap } from 'lucide-react';
+import { ink } from '../../ink/index.ts';
+import { CARD } from '../../scene/index.ts';
+import type { Beats, Placed } from '../../scene/index.ts';
+
+/*
+ * The Beats of a Step, laid over the Map, played again for each new Message.
+ *
+ * 1. Send     the Message's tag sits on the top edge of the card it went
+ *             to, with who Sent it. A Worker that Sent it has its row lit.
+ * 2. Arrow    an arrow draws itself from exactly what Sent it, the Worker's
+ *             row or the Sender's name, out to the right and into the name
+ *             of the card it went to: across cards for a Request, a small
+ *             loop for a Worker Sending to its own Instance.
+ * 3. Command  one chip per Command the Update asked for, on the card's
+ *             bottom edge.
+ *
+ * Each sits on its own card's edges, so it never covers another card.
+ *
+ * The arrow draws itself, the tag lands as it arrives, the Commands after.
+ * When the cards move, a fold say, all of it glides with them. With reduced
+ * motion it is simply there.
+ */
+
+/** In from a card's right edge. */
+const INSET = 10;
+
+const OUT = [0.23, 1, 0.32, 1] as const;
+/** The cards' glide to a new place, which everything here rides with. */
+const MOVE = { duration: 0.42, ease: [0.32, 0.72, 0, 1] } as const;
+
+/** Where on a card's right edge its name is, or one of its Worker's rows. */
+const edgeAt = (card: Placed, worker?: string) => {
+  const name = card.y + CARD.pad + CARD.header / 2;
+  const index = worker
+    ? card.workers.findIndex((row) => row.name === worker)
+    : -1;
+  const states = card.states ? CARD.gap + card.states.length * CARD.line : 0;
+  return {
+    x: card.x + card.width,
+    y:
+      index < 0
+        ? name
+        : card.y +
+          CARD.pad +
+          CARD.header +
+          states +
+          CARD.gap +
+          index * CARD.row +
+          CARD.row / 2,
+  };
+};
+
+/** From what Sent it to the name of the card it went to, out to the right. */
+const arrowOf = (
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+) => {
+  const side =
+    Math.max(from.x, to.x) + (Math.abs(from.y - to.y) < 80 ? 30 : 52);
+  return `M ${from.x + 3} ${from.y} C ${side} ${from.y}, ${side} ${to.y}, ${to.x + 9} ${to.y}`;
+};
+
+export function Beat({
+  beats,
+  where,
+  onPick,
+}: {
+  readonly beats: Beats;
+  /** Where a card is drawn. */
+  readonly where: (id: string) => Placed | undefined;
+  /** Open the Message. */
+  readonly onPick: () => void;
+}) {
+  const still = useReducedMotion();
+  const target = beats.to ? where(beats.to) : undefined;
+  const sent = beats.send ? where(beats.send.at) : undefined;
+  const from = beats.request ? where(beats.request.from) : undefined;
+  const anchor = target
+    ? {
+        right: target.x + target.width,
+        top: target.y,
+        bottom: target.y + target.height,
+      }
+    : sent && {
+        right: sent.x + sent.width,
+        top: sent.y,
+        bottom: sent.y + sent.height,
+      };
+  // An arrow wherever its start is not already the name it ends at.
+  const start = sent && edgeAt(sent, beats.send?.worker);
+  const end = target && edgeAt(target);
+  const arrow =
+    start && end && (start.x !== end.x || start.y !== end.y)
+      ? { start, d: arrowOf(start, end) }
+      : undefined;
+  // The arrow draws itself; the tag lands as it arrives; the Commands after.
+  const landing = still ? 0 : arrow ? 0.3 : 0;
+  const enter = (delay: number) =>
+    still
+      ? { initial: false as const }
+      : {
+          initial: { opacity: 0, scale: 0.92 },
+          animate: { opacity: 1, scale: 1 },
+          transition: { duration: 0.2, ease: OUT, delay },
+        };
+  // Everything rides with the cards when the Map moves.
+  const ride = still ? { duration: 0 } : MOVE;
+
+  return (
+    <div className="pointer-events-none absolute top-0 left-0">
+      {/* 2. Arrow */}
+      {arrow && (
+        <svg
+          className="absolute top-0 left-0 overflow-visible"
+          width={1}
+          height={1}
+          aria-hidden
+        >
+          <defs>
+            <marker
+              id={`kabuki-arrow-${beats.key}`}
+              viewBox="0 0 8 8"
+              refX="6"
+              refY="4"
+              markerWidth="7"
+              markerHeight="7"
+              orient="auto-start-reverse"
+            >
+              <path d="M 0 0 L 8 4 L 0 8 z" style={{ fill: ink('message') }} />
+            </marker>
+          </defs>
+          <motion.circle
+            r={3}
+            style={{ fill: ink('message') }}
+            initial={{
+              cx: arrow.start.x,
+              cy: arrow.start.y,
+              scale: still ? 1 : 0,
+            }}
+            animate={{ cx: arrow.start.x, cy: arrow.start.y, scale: 1 }}
+            transition={{
+              cx: ride,
+              cy: ride,
+              scale: { duration: 0.15, ease: OUT },
+            }}
+          />
+          <motion.path
+            fill="none"
+            strokeWidth={1.75}
+            strokeLinecap="round"
+            style={{ stroke: ink('message') }}
+            markerEnd={`url(#kabuki-arrow-${beats.key})`}
+            initial={{ d: arrow.d, pathLength: still ? 1 : 0 }}
+            animate={{ d: arrow.d, pathLength: 1 }}
+            transition={{
+              d: ride,
+              pathLength: { duration: 0.45, ease: OUT, delay: 0.05 },
+            }}
+          />
+        </svg>
+      )}
+
+      {anchor && (
+        <>
+          <motion.div
+            className="absolute top-0 left-0"
+            initial={{ x: anchor.right - INSET, y: anchor.top }}
+            animate={{ x: anchor.right - INSET, y: anchor.top }}
+            transition={ride}
+          >
+            {/* 1. Send */}
+            <motion.button
+              type="button"
+              onClick={onPick}
+              className="pointer-events-auto flex h-[22px] origin-right items-center gap-1.5 rounded-full border pr-2.5 pl-2 text-[11px] whitespace-nowrap shadow-xs outline-none focus-visible:ring-2"
+              style={{
+                translate: '-100% -50%',
+                backgroundColor: ink('message-soft'),
+                borderColor: `color-mix(in oklch, ${ink('message')} 30%, transparent)`,
+              }}
+              {...enter(landing)}
+            >
+              {from ? (
+                <ArrowUpRight
+                  className="size-3"
+                  style={{ color: ink('message') }}
+                />
+              ) : (
+                <span
+                  className="size-1.5 rounded-full"
+                  style={{ backgroundColor: ink('message') }}
+                />
+              )}
+              <span className="font-medium" style={{ color: ink('message') }}>
+                {beats.tag}
+              </span>
+              {beats.send && (
+                <span className="text-muted-foreground">
+                  {from ? 'asked by' : 'from'} {beats.send.by}
+                </span>
+              )}
+              {!beats.to && (
+                <span className="text-muted-foreground">· dropped</span>
+              )}
+            </motion.button>
+          </motion.div>
+          {beats.commands.length > 0 && (
+            <motion.div
+              className="absolute top-0 left-0"
+              initial={{ x: anchor.right - INSET, y: anchor.bottom }}
+              animate={{ x: anchor.right - INSET, y: anchor.bottom }}
+              transition={ride}
+            >
+              <div
+                className="flex flex-row-reverse gap-1"
+                style={{ translate: '-100% -50%' }}
+              >
+                {/* 3. Command */}
+                {beats.commands.map((command, index) => (
+                  <motion.span
+                    key={`${command.name}-${index}`}
+                    className="flex h-5 origin-top items-center gap-1 rounded-full border px-2 font-mono text-[10.5px] whitespace-nowrap"
+                    style={{
+                      backgroundColor: ink('command-soft'),
+                      borderColor: `color-mix(in oklch, ${ink('command')} 35%, transparent)`,
+                      color: ink('command'),
+                    }}
+                    {...enter(landing + 0.12 + index * 0.05)}
+                  >
+                    <Zap className="size-2.5" />
+                    {command.name}
+                  </motion.span>
+                ))}
+              </div>
+            </motion.div>
+          )}
+        </>
+      )}
+    </div>
+  );
+}

package/src/recipes/kabuki-devtools/map/beat/index.ts

@@ -0,0 +1 @@
+export { Beat } from './beat.tsx';