pixelweaver 0.1.0

package/todo/.done/typed-dispatcher-design.md

@@ -0,0 +1,435 @@
+# Typed Dispatcher Design
+
+Design exploration for tightening end-to-end typing of the command dispatcher
+and cleaning up the loose `CommandContext.getActiveBuffer` surface.
+
+## Context
+
+The PixelWeaver command system uses a single dispatcher singleton. Plugins
+register commands via `api.addCommand<P>(name, definition)`, and any code can
+fire them via `api.dispatch({ type, plugin, version, params })`. A prior
+refactor (I-03 in `todo/.done/audit-implementation-plan.md`) made
+`Command<P>` and `CommandDefinition<P>` generic on the params type, but the
+two ends of the pipe are still untyped.
+
+Two pain points remain:
+
+- **Untyped `dispatch(type, params)`**: `PluginAPI.dispatch` takes
+  `Omit<Command, 'id' | 'timestamp'>` where `Command.params` is
+  `Record<string, unknown>`. The dispatcher looks the definition up in the
+  registry at runtime, and since the registry stores `CommandDefinition<any>`
+  there is no type link between the `type` string and the shape of `params`.
+  As a result every command `execute()` body starts with defensive casts
+  like `const color = params["color"] as string;` and every `api.dispatch`
+  call site spells out a loosely-typed object literal. If the caller forgets
+  a field, the mistake surfaces at runtime, not at compile time.
+
+- **Loose `CommandContext.getActiveBuffer`**: `CommandContext` is declared as
+  `{ getActiveBuffer?: () => PixelBuffer | null; [key: string]: unknown }`.
+  The method is optional and the index signature makes the whole object a
+  typed bag, which forced earlier cast patterns and still forces every
+  caller to write `ctx.getActiveBuffer?.()` followed by a null check.
+  `getActiveBuffer` is called from ~44 sites across 27 files and is
+  effectively non-optional at runtime (it is wired up during bootstrap by
+  `canvas-init-plugin.ts`), yet the type says otherwise.
+
+The goal is to make both sides tight enough that:
+
+- The `type` string in `dispatch()` constrains the shape of `params`.
+- Command `execute()` bodies receive statically-typed `params` and
+  `context` without local casts.
+- `ctx.getActiveBuffer()` (or an equivalent) is non-optional, non-nullable
+  in the common case, and does not require a cast.
+
+## Approaches
+
+### Approach A -- Global command-type-to-params map (module augmentation)
+
+A single ambient interface `CommandParamsMap` maps command type strings to
+their params interfaces. Plugins declare their entries via TypeScript module
+augmentation. The registry, `dispatch()`, and `addCommand()` all derive
+`P` from the `type` string via an index lookup.
+
+```ts
+// In core/command-registry-types.ts
+declare global {
+  interface CommandParamsMap {
+    // populated via module augmentation
+  }
+}
+type CommandType = keyof CommandParamsMap;
+type ParamsOf<T extends CommandType> = CommandParamsMap[T];
+
+// In a plugin file
+interface FloodFillParams { x: number; y: number; color: string }
+declare global {
+  interface CommandParamsMap {
+    flood_fill: FloodFillParams;
+  }
+}
+
+api.addCommand('flood_fill', {
+  execute(params, ctx) {
+    const buffer = ctx.getBuffer();      // typed, non-optional
+    const { x, y, color } = params;      // typed FloodFillParams
+    // ...
+  },
+  // ...
+});
+
+api.dispatch({
+  type: 'flood_fill',
+  plugin: 'builtin/fill',
+  version: '1.0.0',
+  params: { x: 4, y: 2, color: '#f00' }, // required keys enforced
+});
+```
+
+`PluginAPI` would be redefined so that `addCommand` and `dispatch` have
+overloads keyed on `CommandType`:
+
+```ts
+addCommand<T extends CommandType>(
+  name: T,
+  definition: CommandDefinition<ParamsOf<T>>,
+): void;
+
+dispatch<T extends CommandType>(
+  cmd: { type: T; plugin: string; version: string; params: ParamsOf<T> },
+): void;
+```
+
+`CommandContext` becomes a simple interface without an index signature.
+`getActiveBuffer` is renamed to `getBuffer` and made non-optional,
+returning `PixelBuffer` (no `| null`). A new `getBufferOrNull` can be
+provided for the small number of call sites that legitimately want to
+tolerate a missing buffer.
+
+- **Pros**
+  - Single source of truth for command signatures; any code anywhere can
+    look up the params shape by type string.
+  - Callers get autocomplete on the `params` object from the `type` string.
+  - Works across plugin boundaries without explicit imports (important
+    because `ctx.api.dispatch` is called from tool handlers that do not
+    import the command that owns the type).
+  - Zero runtime cost -- all validation happens at the TypeScript layer.
+
+- **Cons**
+  - Module augmentation is global and must be imported for the augmentation
+    to take effect. Forgetting the side-effect import on a plugin boundary
+    silently falls back to `never`/`unknown` for that type.
+  - Collision risk: two plugins cannot register the same command type
+    without TypeScript errors.
+  - `keyof CommandParamsMap` produces large union types that can slow down
+    IDE tooling if the command count grows (currently ~60 commands, which
+    is still comfortable).
+  - Requires rewriting every `execute`/`undo`/`describe` signature and
+    every `api.dispatch` call site. Heavy touch but mechanical.
+
+- **Effort**: Medium-to-large. ~60 command definitions, ~25 dispatch call
+  sites, ~44 `getActiveBuffer` call sites, plus every test that mocks a
+  `CommandContext`. Each plugin file gains a params interface declaration.
+
+### Approach B -- Locally-typed command tokens (phantom-typed handles)
+
+Instead of a global map, `api.addCommand` returns a typed token that
+encodes the params type in its phantom type parameter. Dispatch happens
+through the token, not through a raw string.
+
+```ts
+// Token type carries the params shape as a phantom type parameter.
+interface CommandToken<P> {
+  readonly type: string;
+  readonly plugin: string;
+  readonly version: string;
+  // phantom -- never instantiated
+  readonly __params?: (p: P) => void;
+}
+
+// addCommand returns a token
+const floodFill = api.addCommand('flood_fill', {
+  execute(params: FloodFillParams, ctx) { /* ... */ },
+  undo(params, ctx, snap) { /* ... */ },
+  describe(params) { return `Flood fill at ${params.x},${params.y}`; },
+});
+// floodFill: CommandToken<FloodFillParams>
+
+// Dispatch uses the token, not a raw string
+api.dispatch(floodFill, { x: 4, y: 2, color: '#f00' });
+```
+
+`CommandContext` is cleaned up the same way as Approach A
+(non-optional `getBuffer()`). Raw-string dispatch remains available as an
+untyped escape hatch for dynamic cases (e.g. shortcut routing, action log
+replay).
+
+- **Pros**
+  - Type inference is local -- no global map, no augmentation, no
+    side-effect imports.
+  - Each plugin owns the types for its own commands and exports the tokens
+    it wants other plugins to dispatch.
+  - Natural fit for factory-style plugins that generate commands
+    dynamically at registration time.
+  - Preserves the ability to have two internally-scoped commands with the
+    same name in different plugins without ambient-type collisions.
+
+- **Cons**
+  - Requires cross-plugin imports to dispatch from one plugin's code into
+    another's command (e.g. tool handlers that fire the commands exposed
+    by the drawing-primitives plugin). Today these are decoupled through
+    string dispatch; moving to tokens creates new dependencies.
+  - Action log replay, shortcut routing, and menu contributions all work on
+    raw strings, so a second untyped path must be kept alive -- you get
+    two parallel APIs.
+  - Renaming a command becomes awkward because the string identifier is
+    still the canonical form for serialization but the token is the
+    canonical form for dispatch. Two sources of truth.
+  - The phantom-type trick is unfamiliar to most TS devs; readability
+    suffers slightly.
+
+- **Effort**: Large. Touches every call site that currently uses string
+  dispatch AND introduces new plugin-to-plugin imports, which means the
+  plugin dependency graph must be updated. Likely spawns follow-up
+  refactors to avoid circular plugin references.
+
+### Approach C -- Discriminated union of command descriptors
+
+Instead of a map, a single exported union type enumerates every command
+descriptor. `addCommand` and `dispatch` use a generic that extracts
+the matching member from the union.
+
+```ts
+// In a central types file, one entry per command
+export type CommandDescriptor =
+  | { type: 'flood_fill'; params: { x: number; y: number; color: string } }
+  | { type: 'draw_rect';  params: { x: number; y: number; w: number; h: number; color: string } }
+  | { type: 'blur';       params: { radius: number } }
+  // ...
+  ;
+
+type ParamsFor<T extends CommandDescriptor['type']> =
+  Extract<CommandDescriptor, { type: T }>['params'];
+
+api.addCommand('flood_fill', {
+  execute(params, ctx) {
+    // params inferred as { x: number; y: number; color: string }
+    const buffer = ctx.getBuffer();
+    // ...
+  },
+  // ...
+});
+
+api.dispatch({
+  type: 'flood_fill',
+  plugin: 'builtin/fill',
+  version: '1.0.0',
+  params: { x: 4, y: 2, color: '#f00' },
+});
+```
+
+`CommandContext` is tightened identically to Approach A.
+
+- **Pros**
+  - All command signatures live in one file -- easy to review, easy to
+    grep, easy to detect naming collisions (TS errors immediately).
+  - Switch-exhaustiveness checks work on `cmd.type` throughout the app,
+    useful for action log replay and menu builders.
+  - No module augmentation gymnastics; works with a single explicit import.
+  - Discriminated unions are a mainstream TS idiom, familiar to all devs.
+
+- **Cons**
+  - Central file becomes a bottleneck: every new command requires editing
+    a shared file that every plugin imports. This fights the plugin
+    architecture's intent that plugins own their own surface area.
+  - Scaling: extract over a large union is slower than an index lookup;
+    TS compilation time will grow faster than Approach A as command count
+    climbs.
+  - Third-party plugins cannot extend the union from outside the repo
+    without forking the union definition, which defeats the plugin model
+    the codebase otherwise leans into.
+
+- **Effort**: Medium. Similar call-site churn to Approach A, plus one
+  mechanical pass to move params interfaces into the central union file.
+
+### Comparison
+
+| Dimension                          | A: global map              | B: phantom tokens             | C: central union            |
+|------------------------------------|----------------------------|-------------------------------|-----------------------------|
+| Where types live                   | Alongside each plugin      | Alongside each plugin         | One central file            |
+| Dispatch key                       | String                     | Token object                  | String                      |
+| Requires plugin cross-imports      | No                         | Yes (for cross-plugin calls)  | Just the union module       |
+| Extensible by third-party plugins  | Yes (augmentation)         | Yes (export tokens)           | No (union is closed)        |
+| Autocomplete on `type` string      | Yes                        | n/a (token is the key)        | Yes                         |
+| Autocomplete on `params`           | Yes                        | Yes                           | Yes                         |
+| Supports dynamic string dispatch   | Yes                        | Parallel untyped path         | Yes                         |
+| Works with action log replay       | Yes (string-keyed)         | Needs string fallback         | Yes (string-keyed)          |
+| TS perf at ~60 commands            | Good                       | Great (local inference)       | Good                        |
+| TS perf at ~500 commands           | Acceptable (index lookup)  | Great                         | Degrades (Extract on union) |
+| Familiarity                        | Intermediate               | Advanced                      | Beginner                    |
+| Scales with plugin ecosystem       | Good                       | Fair                          | Poor                        |
+| Effort                             | Medium-to-large            | Large                         | Medium                      |
+
+All three approaches tighten `CommandContext` identically: drop the index
+signature, rename `getActiveBuffer` -> `getBuffer`, make it non-optional,
+return `PixelBuffer` (throw or assert on missing buffer, which cannot
+happen in practice after `canvas-init-plugin` has run). Provide a separate
+`tryGetBuffer()` for the small number of call sites that want to tolerate
+its absence (if any turn out to be real).
+
+## Recommendation
+
+**Approach A (global command-type-to-params map via module augmentation).**
+
+Rationale:
+
+- It is the only approach that matches the existing architecture where
+  plugins are discovered via `import.meta.glob` and communicate with each
+  other through string identifiers routed by the registry. String-keyed
+  dispatch is the codebase's status quo, and Approach A tightens the
+  types without changing that shape.
+- Plugin cross-calls work without new imports. Today, for example,
+  `edit-commands.ts` fires `select_rect` via a string dispatch without
+  importing the selection plugin. Approach B would force that import and
+  create a dependency cycle; Approach A keeps the decoupling.
+- Action log replay, shortcut routing, and menu contributions all
+  naturally stay string-keyed.
+- Module augmentation has a known footgun (forgotten side-effect imports),
+  but this is mitigated by declaring all params interfaces in the same
+  file as `addCommand`, since registering the command and augmenting the
+  map live side by side. Existing lint rules can catch missing imports.
+- Effort is on par with Approach C and substantially lower than Approach B.
+
+The central union (Approach C) is second-best and would be acceptable if
+we wanted a single grep-friendly catalog, but it scales poorly with
+plugin count and fights the plugin model.
+
+## Migration Strategy
+
+Incremental rollout, build stays green at every step.
+
+- **Step 1: Add `CommandParamsMap` infrastructure (non-breaking).**
+  - Create `src/lib/core/command-types.ts` with an empty
+    `interface CommandParamsMap {}` in the global namespace and the
+    `CommandType` / `ParamsOf<T>` helper types.
+  - Leave existing `addCommand<P>` and `dispatch` signatures in place.
+  - No behavior change; build stays green.
+
+- **Step 2: Introduce typed overloads alongside the existing ones.**
+  - Add new overloads of `addCommand` and `dispatch` on `PluginAPI` that
+    key on `CommandType`. Keep the existing generic overloads as a fallback
+    for any command type not yet registered in the map.
+  - Update `PluginAPI.dispatch` to prefer the typed overload when the
+    `type` is known.
+  - No plugin changes required yet; build stays green.
+
+- **Step 3: Tighten `CommandContext` in a single commit.**
+  - Add a new non-optional `getBuffer(): PixelBuffer` method to
+    `CommandContext`, throwing if the dispatcher context has not been
+    initialized (it always is, in practice, by `canvas-init-plugin`).
+  - Keep the old `getActiveBuffer?: () => PixelBuffer | null` method on
+    the interface temporarily so existing call sites continue to compile.
+  - Wire both methods in `canvas-init-plugin.ts`.
+
+- **Step 4: Migrate plugins one at a time.**
+  - For each plugin file, define the params interfaces inline, augment
+    `CommandParamsMap`, rewrite `execute`/`undo`/`describe` to use typed
+    params, and swap `ctx.getActiveBuffer?.()` for `ctx.getBuffer()`.
+  - Drop the `as Type` casts inside the bodies as they become redundant.
+  - One commit per plugin. Order by risk: start with the smallest
+    (e.g. `fill-tool.ts`), end with `drawing-primitives-plugin.ts` and
+    `selection-tool.ts`.
+  - Each commit should keep the tree fully buildable, since untouched
+    plugins still use the old index-signature path.
+
+- **Step 5: Migrate dispatch call sites.**
+  - Once all commands are in the map, sweep for `api.dispatch({ type: ...})`
+    and make sure each call site benefits from the typed overload. No
+    functional change; this is mostly a verification pass that reveals
+    missing/extra params fields as TS errors.
+
+- **Step 6: Remove legacy surface.**
+  - Drop `getActiveBuffer` from `CommandContext`; remove the index
+    signature from `CommandContext`.
+  - Drop the fallback generic overload on `addCommand`/`dispatch`.
+  - Update tests to construct `CommandContext` mocks via a helper that
+    implements `getBuffer()` directly.
+  - Bump the audit doc to reflect the new baseline.
+
+At every step the project compiles, tests pass, and no runtime behavior
+changes. The only commit where TS errors would appear is Step 6, and only
+if a call site was missed in Step 4 or 5.
+
+## Files That Would Change
+
+Core types and dispatcher:
+
+- `src/lib/core/commands.ts` -- tighten `CommandContext`; drop the index
+  signature; add typed helpers.
+- `src/lib/core/dispatcher.ts` -- update context storage type.
+- `src/lib/core/plugin-api.ts` -- new typed overloads of `addCommand` and
+  `dispatch`; pass the typed context.
+- `src/lib/core/plugin-types.ts` -- new `PluginAPI.addCommand`/`dispatch`
+  overloads keyed on `CommandType`.
+- `src/lib/core/registries.svelte.ts` -- `commandRegistry` type updated
+  (still heterogeneous, but no longer needs an explicit `any`).
+- `src/lib/core/command-types.ts` (new) -- declares `CommandParamsMap`,
+  `CommandType`, `ParamsOf<T>`.
+
+Plugins (each gets a params interface and a `CommandParamsMap` augmentation):
+
+- `plugins/builtin/drawing-primitives-plugin.ts`
+- `plugins/builtin/fill-tool.ts`
+- `plugins/builtin/advanced-fill-tool.ts`
+- `plugins/builtin/selection-tool.ts`
+- `plugins/builtin/noise-tool.ts`
+- `plugins/builtin/dither-tool.ts`
+- `plugins/builtin/gradient-tool.ts`
+- `plugins/builtin/pattern-stamp-tool.ts`
+- `plugins/builtin/circle-tool.ts`
+- `plugins/builtin/diamond-tool.ts`
+- `plugins/builtin/line-tool.ts`
+- `plugins/builtin/rect-tool.ts`
+- `plugins/builtin/make-stroke-tool.ts`
+- `plugins/builtin/eyedropper-tool.ts`
+- `plugins/builtin/effects/blur.ts`
+- `plugins/builtin/effects/glow.ts`
+- `plugins/builtin/effects/shadow.ts`
+- `plugins/builtin/effects/outline.ts`
+- `plugins/builtin/effects/sharpen.ts`
+- `plugins/builtin/effects/scale.ts`
+- `plugins/builtin/effects/rotate.ts`
+- `plugins/builtin/effects/flip.ts`
+- `plugins/builtin/effects/color-effects.ts`
+- `plugins/builtin/drawing-utils.ts` -- helpers that read `ctx.getBuffer()`.
+
+UI-level command plugins:
+
+- `src/lib/ui/edit-commands.ts`
+- `src/lib/ui/image-commands.ts`
+- `src/lib/ui/file-commands.ts` (if present in the registration pass)
+- `src/lib/history/history-commands.ts`
+
+Canvas wiring:
+
+- `src/lib/canvas/canvas-init-plugin.ts` -- provide `getBuffer()` in the
+  dispatcher context (plus a guarded error path instead of `| null`).
+
+Tests:
+
+- `plugins/builtin/tool-plugins.test.ts`
+- `plugins/builtin/effects.test.ts`
+- `plugins/builtin/gradient.test.ts`
+- `plugins/builtin/noise-dither.test.ts`
+- `plugins/builtin/selection.test.ts`
+- Any other test that mocks `CommandContext` via `setContext({ getActiveBuffer: ... })`.
+
+Categories of change:
+
+| Category                         | Count (approx) | Change kind                                          |
+|----------------------------------|----------------|------------------------------------------------------|
+| Core type files                  | 5              | Tighten types, add helpers                           |
+| Plugin command files             | ~24            | Add params interfaces + augmentation, drop casts     |
+| UI command files                 | ~4             | Same as plugin command files                         |
+| Dispatch call sites              | ~25            | Benefit from typed overload; fix any real mismatches |
+| `getActiveBuffer` -> `getBuffer` | ~44            | Mechanical rename                                    |
+| Test mock files                  | ~5             | Update `CommandContext` stubs                        |