The plan decomposes the slides-group.md design into 16 TDD-style
tasks across five phases: model and store mutations (Tasks 1-4),
recursive renderer / hit-test / snap (Tasks 5-7), drill-in selection
and shortcut / context-menu / toolbar wiring (Tasks 8-10), connector
partitioning during group() (Task 11), Yorkie adapter and multi-user
convergence tests (Tasks 12-13), PPTX import preservation and
recursive PDF export (Tasks 14-15), and a final task to update
slides.md and archive the work.

Includes the empty-todo lessons companion to be filled in during
implementation.

Foundation for the slides group/ungroup feature. Adds GroupElement
to the Element union so the data model can represent nested groups,
and provides four helpers in model/group.ts (applyGroupTransform,
normalizeToGroupLocal, findElementPath, isDescendantOf) that compose
with the existing PPTX affine-transform math without touching
import/pptx/group.ts. No behaviour change to existing elements.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

- Rename isDescendantOf → isGroupDescendantOf and narrow second
  parameter from Element to GroupElement; makes the cycle-prevention
  contract explicit: the function only walks group subtrees and is
  only meaningful when the target is itself a group.
- Fix misleading "returns true for a direct child" test which only
  exercised the self-check; replace with a genuine direct-group-child
  assertion so all three cases (self, direct child, deep descendant)
  are covered by distinct tests.
- Remove redundant inline comment inside groupToTransform that
  duplicated the JSDoc above.
- Simplify double-negative in normalizeToGroupLocal:
  -(-t.b * t.tx + t.a * t.ty) → (t.b * t.tx - t.a * t.ty).
- Add invariant comment on GroupElement explaining that placeholderRef
  is invalid on groups to prevent future mistakes.
- Update design doc findElementPath signature to match implementation
  (elements: Element[] not slide: Slide).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Implements Task 2 of the slides group/ungroup feature. The `group()`
method validates that all candidate elements exist, share the same
parent, and carry no placeholderRef, then computes the world-AABB from
rotated corners, wraps candidates in a new GroupElement (with
children in group-local coords via normalizeToGroupLocal), and inserts
the group at the front-most selected element's z-order position inside
batch() for single-step undo.

Also adds the `ungroup()` stub (throws "not implemented") and both
signatures to the SlidesStore interface so Task 3 can land without a
breaking interface change.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Move the canonical compose/ancestor helpers into model/group.ts so there
is a single source of truth for slide-group affine math.  The four
private helpers in memory.ts (composeLocalTransforms,
computeAncestorTransform, applyTransformToFrame,
applyInverseTransformToFrame) duplicated logic already in pptx/group.ts
and model/group.ts; replacing them with thin wrappers over the public
API removes ~60 lines and makes the invariants visible at a glance.

The dead Invariant-5 loop (a pair of nested for-loops whose body was
only a comment) is deleted; a single comment explains that cycle
prevention is structurally guaranteed by the shared-parent invariant, so
no runtime check is needed.  The O(n²) indexOf inside .map() is replaced
with an index-based map, and the missing-parentId path in
resolveAncestorTransform now throws instead of silently returning
identity so future refactors cannot hide path-lookup bugs.

A new test locks in the rotation-aware AABB path: a 100×40 shape rotated
90° grouped with an axis-aligned 50×50 shape must produce a frame of
{x:30, y:-30, w:120, h:180, rotation:0}.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

`applyInverseFrameWithTransform` in memory.ts duplicated the
determinant/cofactor arithmetic already present in
`normalizeToGroupLocal`. Extract a public `applyInverseMatrix` helper
in model/group.ts that takes a raw GroupTransform, then refactor
`normalizeToGroupLocal` to delegate to it. Remove the private copy
from memory.ts entirely — callers now import the single implementation
via the model layer.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Children's world frames must survive a group→ungroup round-trip.
`applyGroupTransform(child.frame, group)` bakes the group's affine
transform (translation + rotation) into each child's frame so the
child lands in the group's parent coordinate space — one level only.
Nested GroupElement children have their own `frame` transformed the
same way; their grandchildren stay untouched in their own group-local
space.

Adds five deterministic tests (z-order, rotation composition, error
paths, undo step) and one fast-check property test (50 runs) that
asserts world frames are preserved within floating-point tolerance
across group→ungroup.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Drops the leftover "stub — implemented in Task 3" note now that the
real ungroup is live, and documents the one-level bake invariant so
callers know children land in the immediate parent's coord space (not
absolute slide-root space) when the group itself is nested.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

All MemSlidesStore element mutations (updateElementFrame, updateElementData,
reorderElement, removeElement, removeElements, withTextElement, the three
connector updaters) now use findElementPath so they locate and mutate the
target element at any nesting depth, not just at the slide root.

addElement gains an optional parentGroupId parameter: when provided the new
element is appended to that group's children instead of the slide root.

After any removeElement / removeElements call, pruneEmptyAncestorGroups walks
back up the ancestor path and removes any group that became empty, recursing
until it hits a non-empty group or the slide root. This keeps the tree free
of empty ghost groups without requiring callers to handle cleanup.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Close inconsistency where connectors added into a group skipped the
defensive frame recompute that slide-root connectors received; move the
recompute after both branches so it applies unconditionally.

Mark two flat-walk sites in the Yorkie store (removeElement, reorderElement)
and the keyboard handler (z-order arrow keys) with TODO(group) comments so
they are not forgotten when UI consumers become group-aware in P2/P3.

Replace the `!` non-null assertion in removeElementsByPaths with an
explicit guard and a descriptive throw, so future refactors don't get
caught out by a silent assumption.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Groups become a paint-time recursion: drawElement saves the group's frame
transform (translate + optional rotate/flip) and then iterates its children,
calling drawElement recursively for each. Per-type painters (shape, text,
image) are unchanged — they still receive element-local coordinates and are
unaware they're inside a group. Arbitrary nesting depth is handled naturally
by the recursion.

elementsLookup is now built from flattenElements() instead of the flat
slide.elements array so connector endpoints targeting shapes nested inside
groups resolve correctly. flattenElements() (new export in model/group.ts
and re-exported from index.ts) performs a DFS walk of the element tree and
returns every element at every depth.

Connectors inside groups are left as a TODO per the v1 invariant: group()
never includes connectors as children (Task 11), so the existing early-return
path for connectors is safe. A comment documents the limitation.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Task 8's drill-in selection state machine needs to know the full chain
of ancestor groups containing the clicked element, not just the leaf id.
Introducing hitTestSlide() walks the element tree DFS front-to-back,
transforms each world-space test point into each group's local coordinate
space via the inverse group matrix, and recurses into children.

The existing topmostUnderPoint() in select.ts is reduced to a one-liner
that delegates to hitTestSlide(), preserving all current callers' semantics
(they only consume the leaf-most elementId).

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

The snap engine previously called `boundingBox` nowhere for snap
candidates — the editor's inline collection passed raw `e.frame`
values to `snapDelta`, so rotated shapes and groups snapped against
their un-rotated frame edges rather than the visible rotated bbox.

This commit introduces `collectSnapCandidates` in a new module
`snap-candidates.ts`. At slide-root scope each element (including
groups as a single entry) contributes its rotated AABB; children of
groups are not exposed at root scope. For non-empty `scope` (the
drill-in variant Task 9 will exercise), direct children of the
innermost group are collected with frames composed through the full
ancestor-group transform chain, so they arrive in world coordinates
and still contribute their rotated AABB.

The editor's `startDrag` call site is refactored to call
`collectSnapCandidates(startSlide, [], selectedIds)` instead of the
previous inline `.filter/.map`. `collectSnapCandidates` is also
re-exported from the public `packages/slides/src/index.ts` for
consistency with other editor helpers.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Replace the per-ancestor applyGroupTransform loop in
collectScopedCandidates with a single composeAncestorTransform call
followed by one applyMatrix per child. This is one matrix multiply per
scope level instead of one full apply per ancestor, and makes the
intent clearer. Add a two-level-deep test so Task 9 has a regression
guard against composed-transform regressions.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Google Slides lets users double-click into a group to select children
without ungrouping. This commit adds that hierarchical selection state:

- `Selection.scope` tracks the ancestor-group chain the user has drilled
  into (outer → inner); empty means slide root.
- `click()`, `doubleClick()`, and `escape()` implement the state
  transitions: single click picks outermost ancestor or same-scope
  sibling; double-click drills one level deeper; Escape pops the scope
  stack. Shift+click toggles within the current scope.
- `pickAtScope()` centralises the "outermost vs next-level-down"
  decision, making future callers (drag, resize, rotate) share the same
  logic rather than re-implementing it.
- `applyInversePoint` is moved from a private inline in
  `hit-test-elements.ts` to `model/group.ts` (re-exported from
  `index.ts`) as a Task 6 code-review follow-up — the math is already
  present in `applyInverseMatrix` and belongs next to the rest of the
  group transform utilities.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Drilled-in elements (scope != []) store their frames in group-local
coordinates. Mouse events arrive in world (slide-root) coords. Without
conversion, dragging a grouped child would write a world-space delta
into a local-space frame, visually snapping the element out of position.

Centralise the conversion in `frame-space.ts` (scopeAncestorTransform,
toWorldFrame, fromWorldFrame). These wrap composeAncestorTransform and
applyInverseMatrix from model/group.ts so no matrix math is duplicated.

editor.ts: startDrag, startResize, startRotate all now
  - find elements via the full tree (findElement helper, not flat
    slide.elements.find) so nested elements are reachable,
  - capture world frames at drag start,
  - track world frames throughout the interaction,
  - convert world → local via fromWorldFrame before committing.

paintLiveScoped replaces paintLive: builds a synthetic slide with LOCAL
frames for the canvas renderer (which traverses group hierarchies) and
passes WORLD-frame pseudo-elements to renderOverlay so selection handles
appear at visually correct positions.

keyboard.ts nudge: uses findElementPath + toWorldFrame/fromWorldFrame so
arrow-key moves inside drilled-in groups stay in group-local space.

Phase A + B landed. Phase C (overlay bbox for scoped selection at rest)
not yet handled — the repaintOverlay path still reads stored local frames
for scoped elements, so handles may be offset when not in a live drag.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Task 9 Phase C: repaintOverlay used a flat `slide.elements.filter()`
which only scans slide-root elements. When the user drills into a group
and selects a child, the child id is not in the top-level array, so the
filter returned nothing and no handles were rendered until the user
started dragging (where paintLiveScoped already did the correct
recursive lookup + world-frame conversion).

Fix: replace the flat filter with a recursive `findElement()` lookup for
each selected id, then convert the stored (group-local) frame to world
coords via `toWorldFrame(el.frame, scope, slide)` — the same pattern
paintLiveScoped uses during live drags. For scope=[] the conversion is
the identity, preserving existing behavior for slide-root elements.

Two new tests in editor.test.ts verify that:
- The nw handle lands at the child's WORLD position, not its group-local
  position, after drilling in and selecting a child at rest.
- A child inside a rotated group still gets a CSS-rotated outline,
  confirming the world frame is computed (not the raw stored frame).

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Remove the flat-DFS `topmostUnderPoint` duplicate from editor.ts and
replace all three call sites with `hitTestSlide` from hit-test-elements.ts,
which descends into group children using group-local coordinate transforms
(the Task 6 implementation). This makes right-click, single-click, and
double-click resolve to the correct nested element instead of always
stopping at slide-root.

Route single-click through `Selection.click(hitResult, mods)` so the
drill-in state machine is honoured: clicking inside a group at scope=[]
selects the outermost group rather than the leaf child (Google Slides
behaviour). Route double-click through `Selection.doubleClick(hitResult)`
so the scope descends one level per double-click; if the newly-scoped
element is a text box, text edit mode is entered as before.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Adds the keyboard, context-menu, and toolbar entry-points for
group/ungroup so users have discoverable ways to invoke the store
operations landed in Tasks 3–9. Keyboard shortcuts (Cmd+Alt+G /
Cmd+Shift+Alt+G) keep fingers on the keyboard. Esc now pops one
drill-in scope level before clearing selection, matching Google
Slides. The Arrange dropdown exposes both actions with disabled-
state predicates that mirror the context-menu guards.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

v1 design § 7 rule: a connector that crosses the group boundary (one
endpoint references an element outside the selection) cannot follow the
group — doing so would leave its external endpoint referencing an element
that is no longer a sibling. These connectors must stay at the parent.

MemSlidesStore.group() now partitions candidates into "internal" (both
endpoints in the candidate set or free) and "excluded" cross-boundary
connectors before computing the AABB and normalizing frames. Free
endpoints on internal connectors are converted from parent-local space
to the new group-local space using the ancestor + group transforms.
If exclusion leaves fewer than 2 candidates the call throws.

The editor surfaces the count via an onToast callback so the frontend
(sonner toast.info) can inform the user without the slides package
depending on any UI library.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

MemSlidesStore and Yorkie-backed store must produce identical results
when grouping and ungrouping elements. Without group/ungroup the Yorkie
store fails the SlidesStore interface contract. Nested mutations
(addElement, removeElement, updateElementFrame, updateElementData,
reorderElement, withTextElement, updateConnectorEndpoint/Arrowheads/Stroke)
now walk the Yorkie proxy tree via yorkieFindElementPath so they work on
both slide-root and group-nested elements. Empty groups self-flatten the
same way as MemSlidesStore via pruneEmptyYorkieAncestorGroups. Cross-group
connectors are excluded with the same partition logic and the same
excludedConnectorIds return value. The applyGroupTransformMatrix and
applyGroupTransformToPoint helpers are exported from @wafflebase/slides
so the frontend store can compose ancestor transforms without deep imports.
YorkieGroupElement is added to the type union in slides-document.ts.
read() recurses into group children via readElement() so groups survive
round-trips through the CRDT.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Each group/ungroup mutation must converge under concurrent edits.
Without these tests a silent state divergence between MemSlidesStore
and Yorkie peers could go undetected — the four scenarios (overlapping
group(), ungroup vs drag, concurrent insert, reorder vs delete) cover
the realistic conflict patterns that arise during collaborative editing.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Previously, every <p:grpSp> was flattened: child frames were composed
with a cumulative matrix and emitted directly into slide.elements, losing
all group structure.

Now each <p:grpSp> produces a GroupElement whose frame is the group's
own <a:xfrm> in the parent's coordinate space. Children are stored in
group-local (0..w × 0..h) coords by: (1) composing world transforms
through composeGroupTransform so each child gets a world frame, then
(2) inverting back via applyInverseMatrix / applyInversePoint so frames
and connector free-endpoints land in the enclosing group's local space.

Nested groups recurse naturally — inner groups repeat the same pattern
relative to their own parent group. The bbox-equivalence invariant is
verified by collectLeafWorldFrames tests: leaf world frames computed by
chaining applyGroupTransform up the ancestor path match the values the
old flat-import path produced, within sub-pixel tolerance.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

slides.md removes the group/ungroup entry from "Deferred to v2" and
adds it to a new "Shipped after v1" subsection with a forward link to
slides-group.md; the same entry in "Future parity → Tracked for v2"
is replaced by a "Shipped (post-v1)" bullet.

slides-group.md gains a "Known Limitations / Follow-ups" section
documenting: PDF export not yet implemented (recursive emitter pattern
ready to copy); context-menu Ungroup visibility bug (fix is to route
right-click selection through SelectionController.click); dead
selectAt helper to remove in a follow-up.

Lessons file captures: canonical location for inverse-matrix math,
the applyGroupTransform name collision resolved as
applyGroupTransformMatrix, connector free-endpoint transform gotcha,
PPTX forward/inverse direction convention, and the selectAt dead-code
note.

Task archived via pnpm tasks:archive; tasks index refreshed.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

The previous approach set group.frame to the group's <a:off>/<a:ext>
and inverted via groupToTransform() to recover group-local child coords.
This broke in two ways:

1. When <a:chOff> != <a:off>, the inverse only undid <a:off>+rotation
   but not the chOff translation, so children's world frames started
   outside the handle parallelogram (visible content rendering left of
   the selection handle).

2. <a:ext> is the container bbox, not the visual bbox — it can include
   dead padding around the actual content.

Fix: after recursing children into world space, compute the
rotation-aware AABB via combinedBoundingBox (already used by
MemSlidesStore.group() and YorkieSlidesStore.group()). Set
group.frame to that AABB (rotation=0, tightly bounds visible
content). Convert children to group-local by subtracting the AABB
origin — no matrix inverse needed.

bbox-equivalence invariant (leaf world frames = flat-import world
frames) continues to hold because children's world frames are
unchanged; only the group frame representation differs.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Groups created before the refSize field was introduced have
undefined refSize, which makes the proportional-child-scaling
logic in updateElementFrame a no-op (it skips scaling when
refSize is absent). By capturing the pre-resize dimensions as
the reference inside the startResize onUp batch, the very first
drag on such a group permanently migrates it — subsequent resizes
then scale children correctly without any manual data repair.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

The group-to-transform scale wasn't reaching the canvas: drawElement
used direct ctx.translate/rotate calls that didn't account for the
group's refSize, so children kept their literal frame.w/h positions
instead of scaling proportionally when the group was resized.

Fix: derive scaleX/scaleY from frame.w/refSize.w (and h), emit
ctx.scale(scaleX, scaleY) in the centre-relative path, and use
-refW/2,-refH/2 for the final back-translate. Legacy groups without
refSize default to scale = 1 (no behaviour change).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Re-assigning data as a whole breaks for groups: data.children is a
nested Yorkie.Array proxy, and copying it via object spread exposes
the proxy methods to the next `set`, which Yorkie rejects with
"Unsupported type of value: function". This first showed up when the
resize commit path tried to set refSize on a group via
updateElementData.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Writing refSize at mouseup meant the live preview during the first
resize of a pre-refSize group still saw refSize === undefined, so the
group's children stayed static while the selection box grew —
exactly the "group box grows, children don't" report. Capturing the
migration at mousedown means paintLiveScoped sees refSize during the
drag too, so children scale in real time.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

YorkieSlidesStore.readElement constructed group `data` as
`{ children }` only, dropping any sibling `refSize` field. Every
consumer read through this path, so the renderer never saw refSize
even after migrate-on-resize-start wrote it to Yorkie successfully —
the next read came back undefined and scale fell to 1, leaving
children static while the selection box grew.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

onContextMenu used to set selection to the raw hitTestSlide leaf id,
bypassing the same drill-in state machine that single-click goes
through. Two consequences: (1) right-clicking inside a group landed
selection on the leaf child, whose frame is in group-local coords,
so the overlay rendered handles in the wrong screen position; and
(2) the Ungroup context-menu item was permanently disabled because
the selection never resolved to a GroupElement.

Route the right-click through `selection.click(hitResult, {})` —
matches onPointerDown's path — so the outermost group is picked at
scope=[] and the Ungroup predicate sees the group selection.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

collectSelectedFrames only iterated slide.elements (the top-level
array), so toolbar align / distribute and rotateBy silently no-op'd
on selections inside a drill-in group — the design doc said they
should work on the scope's siblings. Walk via findElementPath and
lift each selected element's frame to world space via toWorldFrame
so the existing align / distribute math (which assumes one consistent
coordinate system) keeps working unchanged. applyFrameUpdates
converts each world frame back through fromWorldFrame before
committing, so the store stores parent-local coordinates.

Also drop the stale "Context menu Ungroup visibility" entry from the
known-limitations section — it was already fixed in the
right-click-through-drill-in commit (18f21eb).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

After rebasing onto main (which migrated input handling to Pointer
Events), the slides-group test still dispatched MouseEvent('mousedown')
and stopped firing — the editor only listens to pointerdown now. Also
set the design doc's target-version to 0.4.2 to reflect the current
release line.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

M1: ungroup() now bakes connector free endpoints from group-local to
parent space (both MemSlidesStore and YorkieSlidesStore). Previously
only the cached `frame` was transformed; `start`/`end` x/y stayed in
group-local coordinates, making connector geometry wrong after ungroup.

M2: applyInverseMatrix/applyInversePoint now throw on a singular
(|det| < 1e-9) group transform instead of silently returning
Infinity/NaN. MemSlidesStore.group() and YorkieSlidesStore.group()
clamp the AABB dimensions to at least 1px so a degenerate group can
never be created in the first place.

M3: scopeAncestorTransform validates the entire scope chain (all
ancestor ids) against the actual path returned by findElementPath. A
stale intermediate scope id from a remote deletion now throws rather
than silently mapping to a wrong ancestry chain.

M4: connector bookkeeping helpers (elementsLookup, detachConnectors
Targeting, updateElementFrame dependent refresh, addElement frame
recompute) now use flattenElements to walk the full element tree,
so connectors and their targets inside groups are handled correctly.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

m5: Add ```text language tags to three fenced code blocks in
docs/design/slides/slides-group.md (schema tree, paintElement pseudo-
code, hitTest pseudo-code) to fix markdownlint MD040 warnings.

m6: Update the stale SlidesStore.group() JSDoc that said
excludedConnectorIds is "always [] until Task 11" — Task 11 has
landed; replace with a description of the actual partition semantics.

m7: Replace the tautological assert.equal(groupId, groupId) in
yorkie-slides-store.test.ts with assert.ok(groupId.length > 0).

m8: Reverse the ancestor-application order in collectLeafWorldFrames
(group-preserving.test.ts) from outer→inner to inner→outer, matching
applyGroupTransform semantics. Pure-translation fixtures happened to
pass either way, but rotated/scaled nested groups would have silently
miscomputed world frames.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

`pnpm tasks:index` regenerates `docs/tasks/README.md` and
`docs/tasks/archive/README.md` deterministically from the directory
tree. Rebasing onto main #264 (which archived 7 more tasks) left
those two files showing stale counts; re-running the script picks
up the new archived tasks while keeping the slides-group archive
entry intact.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>