@operato/scene-ops 10.14.0

package/src/apply-scene.ts

@@ -0,0 +1,397 @@
+/**
+ * Applying edit operations to a scene that is open on screen.
+ *
+ * The difference from `apply-model.ts` is the commander. Everything here goes through
+ * things-scene's own mutation API (`scene.add`, `target.set`, `scene.align`, …), so the
+ * commander records a snapshot and the user keeps undo, the dirty mark and their selection.
+ * Rebuilding the model and handing it back would take all three away.
+ *
+ * The scene is typed `any` on purpose: things-scene's Scene is a large surface and this
+ * module needs eight methods of it. Typing it loosely is what lets the whole file be tested
+ * with a plain object, which is how the operations below are actually covered.
+ */
+import type { ArrangeLayout, SceneActionOp, SceneEditOp } from './ops.js'
+import { mergeComponent } from './apply-model.js'
+
+export interface DispatchContext {
+  /**
+   * Fill an `add` component out with the defaults of its type before it goes in.
+   *
+   * The host does this because the defaults live in its template registry — an editor knows
+   * what a fresh component of each type looks like, and this module does not. Left out, the
+   * component goes to the scene exactly as given.
+   */
+  normalize?: (c: any) => any
+}
+
+export interface DispatchResult {
+  /** False when nothing happened — an unknown refid, too few targets, an op we do not take. */
+  applied: boolean
+  /**
+   * How to undo this one operation, computed from the scene as it was. One operation can
+   * need several: an `align` of five components inverts to five `modify`s.
+   */
+  inverseOps: SceneEditOp[]
+}
+
+const NOOP_RESULT: DispatchResult = { applied: false, inverseOps: [] }
+
+/**
+ * Find a component by refid, or by id when that is all the caller has.
+ *
+ * refid is issued by things-scene to everything in the scene; id is an optional string the
+ * author may have set. refid is tried first because it is the one that is always there.
+ */
+export function findSceneComponent(scene: any, target: { id?: string; refid?: number }): any {
+  if (!scene) return null
+  if (typeof target.refid === 'number') {
+    const byRefid = scene.rootContainer?.refidIndexMap?.get(target.refid)
+    if (byRefid) return byRefid
+  }
+  if (typeof target.id === 'string' && target.id.length > 0) {
+    return scene.findById?.(target.id) ?? null
+  }
+  return null
+}
+
+/**
+ * Carry out one edit operation on a live scene.
+ *
+ * `replace` is not taken here — swapping the whole model is the host's own path, because it
+ * has to decide what happens to the selection and the undo stack.
+ */
+export function dispatchSceneEditOp(
+  scene: any,
+  op: SceneEditOp,
+  ctx: DispatchContext = {}
+): DispatchResult {
+  if (!scene || !op) return NOOP_RESULT
+  const normalize = ctx.normalize ?? ((c: any) => c)
+
+  switch (op.op) {
+    case 'add': {
+      const normalized = normalize(op.component)
+      /* The inverse needs the refid the scene is about to issue, so we diff around the add. */
+      const prevRefids = new Set<number>(collectAllRefids(scene))
+      scene.add(normalized, {})
+      const newRefids = collectAllRefids(scene).filter(r => !prevRefids.has(r))
+      const inverseOps: SceneEditOp[] = newRefids.map(refid => ({ op: 'remove', refid }))
+      return { applied: true, inverseOps }
+    }
+
+    case 'remove': {
+      const target = findSceneComponent(scene, { refid: op.refid })
+      if (!target || !target.parent) return NOOP_RESULT
+      const savedModel = JSON.parse(JSON.stringify(target.model))
+      const prevSelected = scene.selected ?? []
+      scene.selected = [target]
+      scene.remove()
+      scene.selected = prevSelected.filter((c: any) => c !== target)
+      return { applied: true, inverseOps: [{ op: 'add', component: savedModel }] }
+    }
+
+    case 'modify': {
+      const target = findSceneComponent(scene, { refid: op.refid })
+      if (!target) return NOOP_RESULT
+      const oldValues = captureOldKeys(target.model, op.patch as any)
+      const merged = mergeComponent(target.model, op.patch as any)
+      target.set(merged)
+      /* `set` does not push a snapshot by itself — ask the commander for one. */
+      scene.commander?.execute(null, false)
+      return {
+        applied: true,
+        inverseOps: [{ op: 'modify', refid: op.refid, patch: oldValues }]
+      }
+    }
+
+    case 'modifyScene': {
+      const root = scene.root
+      if (!root || typeof root.set !== 'function') return NOOP_RESULT
+      const cleanPatch = { ...((op.patch as any) || {}) }
+      delete cleanPatch.components /* children move by add/remove/modify */
+      const oldValues = captureOldKeys(root.model, cleanPatch)
+      const merged = mergeComponent(root.model, cleanPatch)
+      root.set(merged)
+      scene.commander?.execute(null, false)
+      return { applied: true, inverseOps: [{ op: 'modifyScene', patch: oldValues }] }
+    }
+
+    case 'align': {
+      const targets = op.refids.map(r => findSceneComponent(scene, { refid: r })).filter((c: any) => c)
+      if (targets.length < 2) return NOOP_RESULT
+      const beforeBounds = targets.map((c: any) => ({
+        refid: c.get('refid'),
+        left: c.get('left'),
+        top: c.get('top'),
+        width: c.get('width'),
+        height: c.get('height')
+      }))
+      const prevSelected = scene.selected ?? []
+      scene.selected = targets
+      scene.align(op.direction)
+      scene.selected = prevSelected
+      /* Undo restores the coordinates we read, rather than trying to invert the alignment. */
+      const inverseOps: SceneEditOp[] = beforeBounds.map(b => ({
+        op: 'modify',
+        refid: b.refid,
+        patch: { left: b.left, top: b.top, width: b.width, height: b.height } as any
+      }))
+      return { applied: true, inverseOps }
+    }
+
+    case 'distribute': {
+      const targets = op.refids.map(r => findSceneComponent(scene, { refid: r })).filter((c: any) => c)
+      if (targets.length < 2) return NOOP_RESULT
+      const beforeBounds = targets.map((c: any) => ({
+        refid: c.get('refid'),
+        left: c.get('left'),
+        top: c.get('top')
+      }))
+      const prevSelected = scene.selected ?? []
+      scene.selected = targets
+      /* things-scene spells these in capitals. */
+      scene.distribute(op.axis === 'horizontal' ? 'HORIZONTAL' : 'VERTICAL')
+      scene.selected = prevSelected
+      const inverseOps: SceneEditOp[] = beforeBounds.map(b => ({
+        op: 'modify',
+        refid: b.refid,
+        patch: { left: b.left, top: b.top } as any
+      }))
+      return { applied: true, inverseOps }
+    }
+
+    case 'group': {
+      const targets = op.refids.map(r => findSceneComponent(scene, { refid: r })).filter((c: any) => c)
+      if (targets.length < 2) return NOOP_RESULT
+      const prevRefids = new Set<number>(collectAllRefids(scene))
+      const prevSelected = scene.selected ?? []
+      scene.selected = targets
+      scene.group()
+      scene.selected = prevSelected
+      const newRefids = collectAllRefids(scene).filter(r => !prevRefids.has(r))
+      const inverseOps: SceneEditOp[] = newRefids.map(refid => ({ op: 'ungroup', refid }))
+      return { applied: true, inverseOps }
+    }
+
+    case 'ungroup': {
+      const target = findSceneComponent(scene, { refid: op.refid })
+      if (!target) return NOOP_RESULT
+      const childRefids: number[] = []
+      const children = (target as any).components ?? []
+      for (const child of children) {
+        const r = child.get?.('refid')
+        if (typeof r === 'number') childRefids.push(r)
+      }
+      const prevSelected = scene.selected ?? []
+      scene.selected = [target]
+      scene.ungroup()
+      scene.selected = prevSelected.filter((c: any) => c !== target)
+      const inverseOps: SceneEditOp[] =
+        childRefids.length >= 2 ? [{ op: 'group', refids: childRefids }] : []
+      return { applied: true, inverseOps }
+    }
+
+    case 'zorder': {
+      const target = findSceneComponent(scene, { refid: op.refid })
+      if (!target) return NOOP_RESULT
+      const prevSelected = scene.selected ?? []
+      scene.selected = [target]
+      scene.zorder(op.direction)
+      scene.selected = prevSelected
+      /*
+       * Best effort. forward/backward invert exactly; front/back do not — sending something
+       * to the front and then to the back does not put it back where it was.
+       */
+      const opp: Record<string, 'front' | 'back' | 'forward' | 'backward'> = {
+        forward: 'backward',
+        backward: 'forward',
+        front: 'back',
+        back: 'front'
+      }
+      const dir = opp[op.direction]
+      const inverseOps: SceneEditOp[] = dir ? [{ op: 'zorder', refid: op.refid, direction: dir }] : []
+      return { applied: true, inverseOps }
+    }
+
+    case 'arrange': {
+      /*
+       * things-scene has no native call for this, so the positions are computed here and
+       * written with `set`. Only left/top move; width and height are the author's.
+       */
+      const targets = op.refids.map(r => findSceneComponent(scene, { refid: r })).filter((c: any) => c)
+      if (targets.length < 2) return NOOP_RESULT
+
+      const beforePositions = targets.map((c: any) => ({
+        refid: c.get('refid'),
+        left: c.get('left'),
+        top: c.get('top')
+      }))
+      const sizes = targets.map((c: any) => ({
+        width: typeof c.get('width') === 'number' ? c.get('width') : 0,
+        height: typeof c.get('height') === 'number' ? c.get('height') : 0
+      }))
+
+      const positions = computeArrangePositions(op.layout, beforePositions, sizes)
+      for (let i = 0; i < targets.length; i++) {
+        const t = targets[i]
+        const pos = positions[i]
+        const merged = mergeComponent(t.model, { left: pos.left, top: pos.top } as any)
+        t.set(merged)
+      }
+      /* One snapshot for the whole arrangement — moving twelve things is one undo. */
+      scene.commander?.execute(null, false)
+
+      const inverseOps: SceneEditOp[] = beforePositions.map(b => ({
+        op: 'modify',
+        refid: b.refid,
+        patch: { left: b.left, top: b.top } as any
+      }))
+      return { applied: true, inverseOps }
+    }
+
+    case 'replace':
+      return NOOP_RESULT
+
+    default:
+      return NOOP_RESULT
+  }
+}
+
+/**
+ * Carry out one view action on a live scene.
+ *
+ * Returns false when it could not — an unknown action, a missing component. Nothing here
+ * touches the model, so nothing here enters the undo history.
+ *
+ * `setSceneMode` changes `scene.mode`; a host holding its own reactive copy re-reads it.
+ * things-scene spells the modes 1 for edit and 0 for view.
+ */
+export function dispatchSceneAction(scene: any, action: SceneActionOp): boolean {
+  if (!scene || !action) return false
+  switch (action.action) {
+    case 'selectComponents': {
+      const refids = Array.isArray(action.refids) ? action.refids : []
+      scene.selected = refids.map(r => findSceneComponent(scene, { refid: r })).filter((c: any) => c)
+      return true
+    }
+    case 'centerToComponent': {
+      const target = findSceneComponent(scene, { refid: action.refid })
+      if (!target) return false
+      scene.centerTo(target, action.animated !== false)
+      return true
+    }
+    case 'fitToView': {
+      scene.fit(action.mode ?? 'fit')
+      return true
+    }
+    case 'setSceneMode': {
+      scene.mode = action.mode === 'edit' ? 1 : 0
+      return true
+    }
+    case 'highlightComponents': {
+      /* things-scene's own call — it outlines in 2D and in 3D. */
+      const refids = Array.isArray(action.refids) ? action.refids : []
+      const targets = refids.map(r => findSceneComponent(scene, { refid: r })).filter((c: any) => c)
+      if (typeof scene.highlightSearchResults === 'function') {
+        scene.highlightSearchResults(targets)
+      }
+      if (typeof scene.invalidate === 'function') scene.invalidate()
+      return true
+    }
+    default:
+      return false
+  }
+}
+
+/**
+ * Where each component goes for a grid, row or column arrangement.
+ *
+ *   - Only left/top are produced; sizes are the author's and are left alone.
+ *   - grid cells are as wide and as tall as the largest component, so components of
+ *     different sizes do not overlap. Filled row by row.
+ *   - row and column walk each component's own size plus the gap, and `align` decides the
+ *     cross axis.
+ *   - Without an anchor, the first component's current position is the origin, so the result
+ *     starts where the user is already looking.
+ */
+export function computeArrangePositions(
+  layout: ArrangeLayout,
+  current: Array<{ left: number; top: number }>,
+  sizes: Array<{ width: number; height: number }>
+): Array<{ left: number; top: number }> {
+  if (current.length === 0) return []
+  const anchor = layout.anchor ?? { left: current[0].left, top: current[0].top }
+  const gap = typeof layout.gap === 'number' ? layout.gap : 10
+
+  if (layout.type === 'grid') {
+    const cols = Math.max(1, Math.floor(layout.cols))
+    const cellW = sizes.reduce((m, s) => Math.max(m, s.width), 0)
+    const cellH = sizes.reduce((m, s) => Math.max(m, s.height), 0)
+    return current.map((_, i) => {
+      const row = Math.floor(i / cols)
+      const col = i % cols
+      return {
+        left: anchor.left + col * (cellW + gap),
+        top: anchor.top + row * (cellH + gap)
+      }
+    })
+  }
+
+  if (layout.type === 'row') {
+    const align = layout.align ?? 'start'
+    const maxH = sizes.reduce((m, s) => Math.max(m, s.height), 0)
+    const out: Array<{ left: number; top: number }> = []
+    let cursor = anchor.left
+    for (const s of sizes) {
+      let top = anchor.top
+      if (align === 'center') top = anchor.top + (maxH - s.height) / 2
+      else if (align === 'end') top = anchor.top + (maxH - s.height)
+      out.push({ left: cursor, top })
+      cursor += s.width + gap
+    }
+    return out
+  }
+
+  const align = layout.align ?? 'start'
+  const maxW = sizes.reduce((m, s) => Math.max(m, s.width), 0)
+  const out: Array<{ left: number; top: number }> = []
+  let cursor = anchor.top
+  for (const s of sizes) {
+    let left = anchor.left
+    if (align === 'center') left = anchor.left + (maxW - s.width) / 2
+    else if (align === 'end') left = anchor.left + (maxW - s.width)
+    out.push({ left, top: cursor })
+    cursor += s.height + gap
+  }
+  return out
+}
+
+/**
+ * Every refid currently in the scene.
+ *
+ * Called on both sides of an `add` or a `group`, so that the difference tells us which refids
+ * the scene just issued — which is the only way to write their inverse.
+ */
+export function collectAllRefids(scene: any): number[] {
+  const refids: number[] = []
+  const map = scene?.rootContainer?.refidIndexMap
+  if (map && typeof map.forEach === 'function') {
+    map.forEach((_: any, refid: number) => refids.push(refid))
+  }
+  return refids
+}
+
+/**
+ * The current values of exactly the keys a patch is about to change, deep-cloned.
+ *
+ * This is the patch of the inverse `modify`. A key the model did not have is kept as null,
+ * which the mergers read as "remove it" — so undoing an added key removes it again.
+ */
+export function captureOldKeys(model: any, patch: any): any {
+  const out: any = {}
+  for (const k of Object.keys(patch || {})) {
+    const v = model?.[k]
+    out[k] = v === undefined ? null : JSON.parse(JSON.stringify(v))
+  }
+  return out
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @operato/scene-ops — describing a change to a scene, and carrying it out.
+ *
+ * A scene can be changed while it is stored (a JSON model in a file or a row) or while it is
+ * open (a things-scene Scene with a commander behind it). Those are two appliers, but they
+ * have to agree about what a change *is*, so the vocabulary and both appliers live here
+ * together.
+ *
+ * Nothing here knows who proposed the change. A language model, a template, an importer and
+ * a person dragging a box all produce the same operations.
+ */
+export * from './model.js'
+export * from './ops.js'
+export * from './apply-model.js'
+export * from './apply-scene.js'

package/src/model.ts

@@ -0,0 +1,46 @@
+/**
+ * The scene model — the JSON a things-scene board/scene is stored and loaded as.
+ *
+ * This shape used to be declared in `@things-factory/board-import` as `BoardModel` /
+ * `BoardComponent`, inside a CAD-import pipeline stage. It is not an import concept and it
+ * is not a board concept: it is what a scene *is* on disk. Anything that reads or writes a
+ * scene needs it, so it lives here with the operations that change it.
+ */
+
+/** One component in a scene, and its children if it is a container. */
+export interface SceneComponentModel {
+  /** Domain type, e.g. 'rect', 'twin-resource-card'. */
+  type: string
+  left: number
+  top: number
+  width: number
+  height: number
+  rotation?: number
+  /**
+   * Assigned by things-scene when the component joins a scene, and stable while it stays
+   * there. Every operation below targets components by this, never by `id` — `id` is
+   * optional metadata that most components do not carry.
+   */
+  refid?: number
+  id?: string
+  /** Children, when this component is a group or container. */
+  components?: SceneComponentModel[]
+  /** Components carry their own properties; we do not enumerate them. */
+  [k: string]: any
+}
+
+/**
+ * A whole scene. The root is a component too — it has its own fillStyle, camera, lights and
+ * so on — but it is reached by a separate operation (`modifyScene`) because it has no refid.
+ */
+export interface SceneModel {
+  width?: number
+  height?: number
+  fillStyle?: string
+  /**
+   * Optional: an empty scene, a legacy file, or a model that is itself the root container
+   * may not have it. Always read it as `model.components ?? []`.
+   */
+  components?: SceneComponentModel[]
+  [k: string]: any
+}

package/src/ops.ts

@@ -0,0 +1,92 @@
+/**
+ * Scene edit operations — the vocabulary for describing a change to a scene.
+ *
+ * One vocabulary, two appliers: `apply-model.ts` changes the stored JSON, `apply-scene.ts`
+ * changes a Scene that is open on screen. They live together so they cannot drift.
+ *
+ * ── Targeting ──
+ * Existing components are addressed by `refid` only. things-scene issues one to every
+ * component; `model.id` is optional metadata and is absent more often than not, so it cannot
+ * be a target. There is one channel, not two.
+ *
+ * ── The root ──
+ * The scene root is the top-level parent (things-scene's model-layer) and carries its own
+ * properties: fillStyle, width, height, fitMode, translate, scale, sky, skyColor, exposure,
+ * the hemi/dir light fields, the camera fields. It has no refid, so `modifyScene` reaches it
+ * and `modify` reaches everything else.
+ *
+ * Note that a board's *name* is a column on the board row in the database, not a field of
+ * the scene model. Sending it through `modifyScene` writes a dead key into the JSON and
+ * changes nothing on screen.
+ */
+import type { SceneComponentModel, SceneModel } from './model.js'
+
+export type AlignDirection = 'left' | 'right' | 'center' | 'top' | 'middle' | 'bottom'
+
+export type DistributeAxis = 'horizontal' | 'vertical'
+
+export type ZorderDirection = 'front' | 'back' | 'forward' | 'backward'
+
+/**
+ * The layout an `arrange` operation asks for.
+ *
+ * This sits above align/distribute so that "in a 3x2 grid", "in one row", "in a column"
+ * is one operation rather than a list of coordinates.
+ *
+ * Only left/top change — width and height are kept. Changing size is a separate `modify`.
+ *
+ * Positions are computed by the scene applier, because they need each component's current
+ * width and height. The model applier treats `arrange` as a no-op.
+ */
+export type ArrangeLayout =
+  | { type: 'grid'; cols: number; gap?: number; anchor?: { left: number; top: number } }
+  | {
+      type: 'row'
+      gap?: number
+      anchor?: { left: number; top: number }
+      align?: 'start' | 'center' | 'end'
+    }
+  | {
+      type: 'column'
+      gap?: number
+      anchor?: { left: number; top: number }
+      align?: 'start' | 'center' | 'end'
+    }
+
+/** An operation that changes the scene. */
+export type SceneEditOp =
+  | { op: 'add'; component: SceneComponentModel }
+  | { op: 'remove'; refid: number }
+  | { op: 'modify'; refid: number; patch: Partial<SceneComponentModel> }
+  | { op: 'modifyScene'; patch: Partial<SceneModel> }
+  | { op: 'replace'; model: SceneModel }
+  | { op: 'align'; refids: number[]; direction: AlignDirection }
+  | { op: 'distribute'; refids: number[]; axis: DistributeAxis }
+  | { op: 'group'; refids: number[] }
+  | { op: 'ungroup'; refid: number }
+  | { op: 'zorder'; refid: number; direction: ZorderDirection }
+  | { op: 'arrange'; refids: number[]; layout: ArrangeLayout }
+
+/**
+ * An operation that changes what the viewer sees but not what the scene is.
+ *
+ * Separate from `SceneEditOp` on purpose: these leave the model alone, so they do not enter
+ * the undo history and do not make the document dirty. A host that mixes the two ends up
+ * asking the user to save because the AI scrolled the view.
+ */
+export type SceneActionOp =
+  | { action: 'selectComponents'; refids: number[] }
+  | { action: 'centerToComponent'; refid: number; animated?: boolean }
+  | { action: 'fitToView'; mode?: 'fit' | 'ratio' | 'width' | 'height' }
+  | { action: 'setSceneMode'; mode: 'edit' | 'view' }
+  /** Outline several components at once — the "these are all the matches" of a search. */
+  | { action: 'highlightComponents'; refids: number[] }
+
+/** A batch of edit operations, with whatever the proposer wants to say about them. */
+export interface SceneEditPatch {
+  ops: SceneEditOp[]
+  /** One or two sentences, for the person who has to approve it. */
+  summary: string
+  /** 0..1 */
+  confidence: number
+}