@substrate-kit/cli 0.1.2 → 0.2.0

package/docs/components/controls-timeline.mdx

@@ -0,0 +1,107 @@
+---
+title: Controls timeline
+description: Animation clips defined in code and tuned in a timeline editor.
+---
+
+Define animation clips as a plain object, bind their values to your UI, and tune their timing and curves in a timeline. `ControlsTimeline` is the editor: scrub the playhead, drag a clip to move it, drag its edges to resize it, and click it to edit its values with the same rows as [Controls](/docs/components/controls).
+
+The clip model and playback come from [DialKit](https://github.com/joshpuckett/dialkit) by Josh Puckett (MIT). Substrate uses its headless timeline and supplies the interface.
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/controls-timeline
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="controls-timeline-demo" />
+
+## Usage
+
+```tsx
+import { ControlsTimeline } from "@/components/substrate/controls-timeline"
+import { useControlsTimeline } from "@/hooks/substrate/use-controls-timeline"
+
+function Card() {
+  const timeline = useControlsTimeline("Card", {
+    enter: {
+      at: 0,
+      duration: 0.6,
+      from: { y: 24, opacity: 0 },
+      to: { y: 0, opacity: 1 },
+      transition: { type: "spring", visualDuration: 0.5, bounce: 0.2 },
+    },
+  })
+
+  const { y, opacity } = timeline.enter.current
+
+  return (
+    <>
+      <div style={{ opacity, transform: `translateY(${y}px)` }}>Card</div>
+      <ControlsTimeline />
+    </>
+  )
+}
+```
+
+`clip.current` holds the clip's values at the playhead, so the element is exactly where the timeline says whether it is playing, paused or being scrubbed.
+
+## Clips
+
+| Clip | Definition | Editing |
+| --- | --- | --- |
+| From–to | `{ at, duration, from, to, transition }` | Drag to move, drag either edge to resize. Physics springs set their own length. |
+| Sequence | `{ at, from, steps: [{ duration, to, transition }] }` | One bar split into steps. Drag a boundary to retime a step. |
+| Property tracks | `{ at, props: { blur: { from, to, duration, delay } } }` | Expand the clip to show a row per property. Drag a row to change its delay. |
+| Group | `{ intro: { title: {...}, badge: {...} } }` | Nested clips show under a collapsible row. |
+
+Add `loop: true` to a clip to repeat it until the timeline ends. Faded bars show the repeats. When the whole timeline loops, the ruler shades the part that repeats, starting at `loop.from`.
+
+## useControlsTimeline
+
+```ts
+const timeline = useControlsTimeline(name, config, options)
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | — | Keeps values across unmounts and shares them between mounts using the same id |
+| `persist` | `boolean \| { key?, storage?, presets? }` | — | Saves values to browser storage |
+| `autoplay` | `boolean` | `true` | Start playing on mount |
+| `loop` | `boolean \| { from: number }` | `false` | Loop at the end, or wrap back to `from` so earlier clips play once |
+
+The result has `time`, `playing`, `duration`, `play()`, `pause()`, `replay()` and `seek(seconds)`, plus one entry per clip:
+
+| Clip value | Description |
+| --- | --- |
+| `current` | Values at the playhead |
+| `from`, `to`, `animate` | The clip's end states; `animate` is `to` once the clip has started |
+| `transition`, `css` | The clip's curve, as a Motion transition or CSS duration and timing function |
+| `started`, `active`, `done`, `progress`, `step` | Where the playhead is relative to the clip |
+
+## ControlsTimeline
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `timeline` | `string` | — | Render only the timeline with this name or id. Renders every timeline when omitted. |
+| `resize` | `"top" \| "bottom" \| false` | `"top"` | Where the handle for resizing the height sits. Use `"top"` for a timeline docked at the bottom of the screen. |
+| `defaultHeight` | `number` | — | Starting height limit in pixels. Unlimited when omitted. |
+| `minHeight` | `number` | `120` | Smallest height the handle allows |
+
+Drag the handle, or focus it and use the arrow keys, to limit the height. The rows then scroll under the header and ruler. Double-click the handle to fit the content again.
+
+The header has play and pause, replay, the clock, zoom, versions and a copy button. Copy gives an agent the tuned values to apply as the new defaults. Keep the `current` bindings while tuning, then move the values into your production animation.
+
+### Zoom
+
+Use the zoom buttons, or hold Ctrl or ⌘ and scroll (or pinch on a trackpad) to zoom around the pointer. While zoomed, scroll sideways or hold Shift and scroll to pan, or drag the window in the overview strip below the clips. The view follows the playhead during playback, and **Fit** shows the whole timeline again.
+
+## Theme variables
+
+| Variable | Fallback | Description |
+| --- | --- | --- |
+| `--timeline-clip` | Primary at 18% | Clip bar fill |
+| `--timeline-playhead` | `--color-destructive` | Playhead colour |

package/docs/components/controls.mdx

@@ -0,0 +1,168 @@
+---
+title: Controls
+description: Config-driven control panels – describe parameters as an object and render them with Substrate controls.
+---
+
+Describe a panel as a plain object and get typed values back. `Controls` renders every registered panel with Substrate's own components, so it sits inside a `Panel` like any hand-built pane.
+
+The config format and store come from [DialKit](https://github.com/joshpuckett/dialkit) by Josh Puckett (MIT). Substrate uses its headless store and supplies the interface.
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/controls
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="controls-demo" />
+
+## Usage
+
+```tsx
+import { Panel } from "@/components/substrate/panel"
+import { Controls } from "@/components/substrate/controls"
+import { useControls } from "@/hooks/substrate/use-controls"
+
+function Editor() {
+  const card = useControls("Card", {
+    radius: [16, 0, 48],
+    colour: "#a78bfa",
+    visible: true,
+    shadow: { blur: [24, 0, 64] },
+  })
+
+  return (
+    <>
+      <div style={{ borderRadius: card.radius, background: card.colour }} />
+      <Panel>
+        <Controls />
+      </Panel>
+    </>
+  )
+}
+```
+
+Keys become labels, and the returned values keep the same nesting as the config.
+
+## Config
+
+| Control | Definition | Returned value | Rendered with |
+| --- | --- | --- | --- |
+| Slider | `radius: [16, 0, 48]` | `number` | NumberSlider |
+| Slider with step | `radius: [16, 0, 48, 2]` | `number` | NumberSlider |
+| Inferred slider | `scale: 1.2` | `number` | NumberSlider |
+| Toggle | `visible: true` | `boolean` | Toggle |
+| Text | `title: "Hello"` | `string` | TextArea |
+| Colour | `colour: "#a78bfa"` | `string` | ColourPicker |
+| Select | `align: { type: "select", options: ["left", "right"] }` | `string` | Select |
+| Easing | `motion: { type: "easing", duration: 0.3, ease: [0.25, 0.1, 0.25, 1] }` | `{ type, duration, ease }` | EasingCurveEditor |
+| Spring (time) | `motion: { type: "spring", visualDuration: 0.3, bounce: 0.2 }` | `{ type, visualDuration, bounce }` | SpringEditor |
+| Spring (physics) | `motion: { type: "spring", stiffness: 200, damping: 25, mass: 1 }` | `{ type, stiffness, damping, mass }` | SpringEditor |
+| Image | `cover: { type: "image", options: ["/a.jpg", "/b.jpg"] }` | `string` (URL or data URL) | ImagePicker |
+| XY pad | `offset: { type: "pad", x: [0, -50, 50, 1], y: [0, -50, 50, 1] }` | `{ x, y }` | XYPad |
+| Action | `replay: { type: "action" }` | Calls `onAction("replay")` | Button |
+| Folder | `shadow: { blur: [24, 0, 64] }` | Nested values | CollapsiblePane |
+
+Slider tuples are `[default, min, max, step?]`. Add `_collapsed: true` inside a folder to start it closed.
+
+Easing and spring controls share one row with an Easing / Time / Physics switch, as in DialKit. Switching changes the shape of the returned value, and switching back restores the previous settings. Uploaded images are stored as data URLs, so prefer `options` for large images when persisting values.
+
+## useControls
+
+```ts
+const values = useControls(name, config, options)
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Keeps values across unmounts and shares them between mounts using the same id |
+| `persist` | `boolean \| { key?, storage?, presets? }` | Saves values to browser storage |
+| `onAction` | `(path: string) => void` | Called with the path of a clicked action control |
+| `shortcuts` | `Record<string, ShortcutConfig>` | Keyboard shortcuts for sliders and toggles, by control path |
+
+### Shortcuts
+
+```tsx
+const card = useControls("Card", {
+  radius: [16, 0, 48],
+  shadow: { blur: [24, 0, 64] },
+  visible: true,
+}, {
+  shortcuts: {
+    radius: { key: "r", mode: "fine" },
+    "shadow.blur": { key: "b", interaction: "drag" },
+    visible: { key: "v" },
+  },
+})
+```
+
+Hold **R** and scroll to adjust the radius, hold **B** and drag to adjust the blur, and press **V** to toggle visibility. Holding a slider's key also lets the arrow keys step it. The row being adjusted is highlighted, and each row shows its key next to the label.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `key` | `string` | — | The key to hold or press |
+| `modifier` | `"alt" \| "shift" \| "meta"` | — | A modifier that must also be held |
+| `interaction` | `"scroll" \| "drag" \| "move" \| "scroll-only"` | `"scroll"` | How a held slider key adjusts the value. `"scroll-only"` needs no key and claims every scroll, so use it sparingly. |
+| `mode` | `"fine" \| "normal" \| "coarse"` | `"normal"` | Step size: 1% of the range, the slider's step, or 10% of the range |
+
+Shortcuts pause while a text field, select or menu has focus, so typing is never captured.
+
+### Setting values from code
+
+`useControlsController` registers the same panel and also returns setters, for loading a saved state or applying a preset:
+
+```tsx
+const parameters = useControlsController("Parameters", {
+  steps: [30, 1, 100, 1],
+  cfgScale: [7, 1, 20, 0.5],
+})
+
+parameters.values.steps
+parameters.setValues({ steps: 40 })
+parameters.reset()
+```
+
+### Values that belong to a selection
+
+A panel owns its values, which suits settings with local state. When the values belong to something selectable, mount a small component per selection with `key`, seed the config from the selected item, and write edits back:
+
+```tsx
+function MaterialControls({ object, onChange }: Props) {
+  const [config] = useState(
+    () =>
+      ({
+        colour: object.colour,
+        roughness: [object.roughness, 0, 1, 0.01],
+      }) satisfies ControlsConfig,
+  )
+  const material = useControls("Material", config)
+
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+  useEffect(() => {
+    onChangeRef.current(material)
+  }, [material])
+
+  return <Controls panel="Material" />
+}
+
+<MaterialControls key={selected.id} object={selected} onChange={update} />
+```
+
+This works when nothing else edits those values while the item is selected. If they also change elsewhere (dragging on a canvas, undo), compose the individual controls by hand so they read straight from your store.
+
+## Controls
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `panel` | `string` | — | Render only the panel with this name or id. Renders every panel when omitted. |
+
+Each panel header has these actions:
+
+- **Keyboard shortcuts** lists the panel's shortcuts. It only appears when the panel has some.
+- **Versions** switches between versions of the panel's values. Edits apply to the version you are on, and **New version** starts a copy of the current values. Version 1 is the values before any version was made. Versions last for the session, or are saved with the values when `persist` is set with `presets: true`.
+- **Copy values** copies the current values as an instruction for an agent to make them the new defaults in the `useControls` call.
+- **Reset** restores the config defaults.

package/docs/components/design-canvas.mdx

@@ -0,0 +1,51 @@
+---
+title: Design Canvas
+description: The main canvas component for rendering and interacting with design elements.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/design-canvas
+```
+
+## Usage
+
+```tsx
+import { DesignCanvas } from "@/components/substrate/design-canvas"
+
+export default function Editor() {
+	return (
+		<div className="h-screen w-screen">
+			<DesignCanvas />
+		</div>
+	)
+}
+```
+
+## Features
+
+- HTML5 Canvas 2D rendering with `requestAnimationFrame` loop
+- DPR-aware sizing for sharp rendering on retina displays
+- Dirty-flag optimization — only re-renders when state changes
+- Pointer event handling for create, move, resize, pan, and marquee select
+- Keyboard shortcuts for tool switching, undo/redo, delete, and zoom
+- Cursor changes based on active tool
+
+## Theme variables
+
+| Variable              | Tailwind class           | Fallback             | Description              |
+| --------------------- | ------------------------ | -------------------- | ------------------------ |
+| `--canvas`            | `bg-canvas`              | `--background`       | Canvas background colour |
+| `--canvas-foreground` | `text-canvas-foreground` | `--foreground-muted` | Grid dots and canvas UI  |
+
+Override in your `globals.css` `:root` / `.dark` blocks to theme the canvas.
+
+## Dependencies
+
+The canvas component pulls in the full interaction stack:
+
+- `tool-store` — active tool state
+- `use-canvas-renderer` — render loop
+- `use-canvas-interaction` — pointer events
+- `use-keyboard-shortcuts` — keyboard handling

package/docs/components/document-tabs.mdx

@@ -0,0 +1,25 @@
+---
+title: Document tabs
+description: Multi-document tab bar built on Radix Tabs with closeable tabs.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/document-tabs
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="document-tabs-demo" />
+
+## Components
+
+| Component            | Description                                |
+| -------------------- | ------------------------------------------ |
+| `DocumentTabs`       | Root wrapper (Radix Tabs.Root)             |
+| `DocumentTabList`    | Horizontal scrollable tab bar              |
+| `DocumentTab`        | Individual tab with optional close button  |
+| `DocumentTabContent` | Content panel displayed for the active tab |

package/docs/components/easing-curve-editor.mdx

@@ -0,0 +1,85 @@
+---
+title: Easing curve editor
+description: Interactive cubic bezier editor with draggable control points and preset buttons.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/easing-curve-editor
+```
+
+This also installs the `easing` utility library.
+
+## Examples
+
+### Default
+
+<ComponentPreview name="easing-curve-editor-demo" />
+
+### Canvas only
+
+<ComponentPreview name="easing-curve-canvas-only" />
+
+## Theme variables
+
+| Variable          | Tailwind class     | Fallback    | Description         |
+| ----------------- | ------------------ | ----------- | ------------------- |
+| `--easing-curve`  | `bg-easing-curve`  | Text colour | Bezier curve stroke |
+| `--easing-handle` | `bg-easing-handle` | Text colour | Control point fill  |
+
+## Components
+
+| Component           | Description                                                                    |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `EasingCurveEditor` | Combines canvas and presets in a vertical stack                                |
+| `EasingCurveCanvas` | Canvas-rendered bezier curve with draggable control points via pointer capture |
+| `EasingPresets`     | Row of buttons for common easing presets (linear, ease-in, ease-out, etc.)     |
+
+## Props
+
+### EasingCurveEditor
+
+| Prop       | Type                            | Default | Description               |
+| ---------- | ------------------------------- | ------- | ------------------------- |
+| `value`    | `CubicBezier`                   | —       | Current bezier value      |
+| `onChange` | `(bezier: CubicBezier) => void` | —       | Called when value changes |
+
+### EasingCurveCanvas
+
+| Prop       | Type                            | Default | Description               |
+| ---------- | ------------------------------- | ------- | ------------------------- |
+| `value`    | `CubicBezier`                   | —       | Current bezier value      |
+| `onChange` | `(bezier: CubicBezier) => void` | —       | Called when value changes |
+| `width`    | `number`                        | `200`   | Canvas width in pixels    |
+| `height`   | `number`                        | `160`   | Canvas height in pixels   |
+
+### EasingPresets
+
+| Prop       | Type                            | Default | Description                   |
+| ---------- | ------------------------------- | ------- | ----------------------------- |
+| `value`    | `CubicBezier`                   | —       | Current bezier for highlight  |
+| `onChange` | `(bezier: CubicBezier) => void` | —       | Called when preset is clicked |
+
+## Easing utility
+
+The `easing` library provides types and helpers:
+
+```tsx
+import {
+	CubicBezier,
+	EASING_PRESETS,
+	evaluateCubicBezier,
+	cubicBezierToString,
+	parseCubicBezier,
+} from "@/lib/substrate/easing"
+```
+
+| Export                | Description                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `CubicBezier`         | Type: `{ x1, y1, x2, y2 }`                                                                                 |
+| `EASING_PRESETS`      | 7 named presets (linear, ease-in, ease-out, ease-in-out, ease-in-cubic, ease-out-cubic, ease-in-out-cubic) |
+| `evaluateCubicBezier` | Evaluate curve at time `t` using Newton's method (8 iterations)                                            |
+| `cubicBezierToString` | Convert to CSS `cubic-bezier(x1, y1, x2, y2)` string                                                       |
+| `parseCubicBezier`    | Parse a CSS cubic-bezier string back to object                                                             |
+| `isCubicBezierEqual`  | Compare two bezier values for equality                                                                     |

package/docs/components/empty-state.mdx

@@ -0,0 +1,26 @@
+---
+title: Empty state
+description: Placeholder for empty panels, lists, and canvases. Icon, title, description, and optional action.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/empty-state
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="empty-state-demo" />
+
+## Components
+
+| Component               | Description                                  |
+| ----------------------- | -------------------------------------------- |
+| `EmptyState`            | Centred flex container with vertical spacing |
+| `EmptyStateIcon`        | Rounded icon container                       |
+| `EmptyStateTitle`       | Short heading                                |
+| `EmptyStateDescription` | Descriptive text, max-width constrained      |
+| `EmptyStateAction`      | Primary action button                        |

package/docs/components/gallery.mdx

@@ -0,0 +1,60 @@
+---
+title: Gallery
+description: Responsive thumbnail grid with selection, hover actions, and empty state.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/gallery
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="gallery-demo" />
+
+### Empty state
+
+<ComponentPreview name="gallery-empty" />
+
+## Theme variables
+
+| Variable              | Tailwind class           | Fallback    | Description           |
+| --------------------- | ------------------------ | ----------- | --------------------- |
+| `--gallery-selection` | `ring-gallery-selection` | `--primary` | Selection ring colour |
+
+## Components
+
+| Component       | Description                                                              |
+| --------------- | ------------------------------------------------------------------------ |
+| `Gallery`       | CSS grid container with configurable columns and gap                     |
+| `GalleryItem`   | Aspect-square cell with selection ring, hover overlay, and click handler |
+| `GalleryImage`  | `<img>` with `object-cover` filling the item                             |
+| `GalleryAction` | Button overlaid on hover in the top-right corner of an item              |
+| `GalleryEmpty`  | Full-width placeholder spanning all columns                              |
+
+## Props
+
+### Gallery
+
+| Prop      | Type     | Default | Description                          |
+| --------- | -------- | ------- | ------------------------------------ |
+| `columns` | `number` | `3`     | Number of grid columns               |
+| `gap`     | `number` | `2`     | Gap between items (in 0.25rem units) |
+
+### GalleryItem
+
+| Prop       | Type         | Default | Description          |
+| ---------- | ------------ | ------- | -------------------- |
+| `selected` | `boolean`    | `false` | Shows selection ring |
+| `onSelect` | `() => void` | —       | Click handler        |
+
+### GalleryImage
+
+Extends `React.ComponentProps<"img">`.
+
+### GalleryAction
+
+Extends `React.ComponentProps<"button">`.

package/docs/components/history-controls.mdx

@@ -0,0 +1,47 @@
+---
+title: History controls
+description: Undo and redo buttons that read from the document store. Position-agnostic — use inside a toolbar, panel header, or floating independently.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/history-controls
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="history-controls-demo" />
+
+### Inside a toolbar
+
+<ComponentPreview name="history-controls-toolbar" />
+
+## Components
+
+| Component         | Description                                        |
+| ----------------- | -------------------------------------------------- |
+| `HistoryControls` | Inline flex container with undo and redo buttons   |
+| `HistoryButton`   | Individual icon button with disabled state styling |
+
+## Props
+
+### HistoryControls
+
+| Prop   | Type           | Default | Description          |
+| ------ | -------------- | ------- | -------------------- |
+| `size` | `"sm" \| "md"` | `"md"`  | Button and icon size |
+
+Extends `React.ComponentProps<"div">`.
+
+## Behaviour
+
+The component reads directly from the document store:
+
+- **Undo** is enabled when `past.length > 0`
+- **Redo** is enabled when `future.length > 0`
+- Disabled buttons drop to 30% opacity and ignore pointer events
+
+Keyboard shortcuts (`Cmd+Z` / `Cmd+Shift+Z`) are handled separately in `use-keyboard-shortcuts` — this component only provides the visual controls.

package/docs/components/image-picker.mdx

@@ -0,0 +1,50 @@
+---
+title: Image picker
+description: Thumbnail grid for choosing an image from a list, with upload and drag-and-drop.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/image-picker
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="image-picker-demo" />
+
+## Usage
+
+```tsx
+const [image, setImage] = useState("/textures/paper.jpg")
+
+<ImagePicker
+  value={image}
+  onChange={setImage}
+  options={[
+    { value: "/textures/paper.jpg", label: "Paper" },
+    "/textures/grain.png",
+  ]}
+/>
+```
+
+Plain string options are labelled from their file name. Uploaded and dropped files are read as data URLs and added to the grid for as long as the picker is mounted. A value that isn't in the list, such as one restored from storage, still shows as selected.
+
+## Theme variables
+
+| Variable                  | Tailwind class               | Fallback      | Description             |
+| ------------------------- | ---------------------------- | ------------- | ----------------------- |
+| `--image-picker-selection` | `bg-image-picker-selection` | Primary colour | Selected image ring    |
+
+## Props
+
+| Prop       | Type                                           | Default | Description                                   |
+| ---------- | ---------------------------------------------- | ------- | --------------------------------------------- |
+| `value`    | `string`                                       | —       | Selected image URL, or `""` for none          |
+| `onChange` | `(value: string) => void`                      | —       | Called with the chosen or uploaded image      |
+| `options`  | `(string \| { value: string, label: string })[]` | `[]`  | Images to choose from                         |
+| `upload`   | `boolean`                                      | `true`  | Show the upload tile and accept dropped files |
+| `columns`  | `number`                                       | `4`     | Thumbnails per row                            |
+| `disabled` | `boolean`                                      | `false` | Disables choosing and uploading               |

package/docs/components/layer-list.mdx

@@ -0,0 +1,36 @@
+---
+title: Layer list
+description: Reorderable layer panel with visibility, lock toggles, and inline rename.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/layer-list
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="layer-list-demo" />
+
+## Interaction
+
+- **Click** a row to select it.
+- **Double-click** the name to rename inline. Press Enter to confirm or Escape to cancel.
+- **Visibility toggle** — hides/shows the layer.
+- **Lock toggle** — locks the layer to prevent selection or editing.
+
+## Components
+
+| Component               | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `LayerList`             | Vertical flex container for layer items          |
+| `LayerItem`             | Row with selection, hover, and depth indentation |
+| `LayerIcon`             | Colour dot or icon thumbnail                     |
+| `LayerName`             | Truncated name with double-click-to-rename       |
+| `LayerActions`          | Right-aligned action slot, visible on hover      |
+| `LayerToggle`           | Generic toggle button for layer actions          |
+| `LayerVisibilityToggle` | Convenience eye/eye-off toggle                   |
+| `LayerLockToggle`       | Convenience lock/unlock toggle                   |