pict-editor-timeline 0.0.1

package/DESIGN.md

@@ -0,0 +1,307 @@
+# pict-editor-timeline — Design Spec
+
+## Purpose
+
+A standalone Pict view library that renders a visual timeline editor
+for building multi-beat video storyboards. Users add, remove, reorder,
+and configure "cuts" — each cut has a text prompt, a duration, and
+optional start/end frame image slots. The editor exports a JSON array
+that any downstream system (retold-labs, ComfyUI, a CLI tool) can
+consume without knowing about the editor.
+
+The library has **zero knowledge** of retold-labs, Ultravisor, model
+weights, or video generation. It is a pure UI component for
+assembling a sequence of annotated time segments with optional image
+references.
+
+## Module location
+
+```
+retold/modules/pict/pict-editor-timeline/
+```
+
+Standard Pict ecosystem module alongside `pict-section-form`,
+`pict-section-formeditor`, `pict-provider-list`, etc.
+
+## Data model
+
+The timeline editor operates on a single data structure: an ordered
+array of **cuts**. Each cut is a plain object:
+
+```javascript
+{
+    // Identity
+    id: "cut-0",                      // Auto-assigned, stable across reorders
+
+    // Content
+    prompt: "A woman walks through a garden at golden hour",
+    target_seconds: 3,
+
+    // Image references (opaque strings — could be file paths,
+    // data URLs, LabAsset GUIDs, or anything the host app provides)
+    start_image: "",                  // First frame reference
+    end_image: "",                    // Last frame reference (optional)
+
+    // UI state (not exported)
+    _collapsed: false,
+    _dragOver: false
+}
+```
+
+### Export format
+
+The `getStoryboard()` method returns a clean JSON array with only the
+fields the storyboard workflow consumes:
+
+```json
+[
+    {
+        "prompt": "A woman walks through a garden at golden hour",
+        "target_seconds": 3,
+        "beat_image": "/path/to/garden.jpg"
+    },
+    {
+        "prompt": "She bends down to pick a flower",
+        "target_seconds": 2
+    }
+]
+```
+
+Mapping: `start_image` → `beat_image` (the storyboard worker's
+field name). `end_image` is advisory — it helps the user visualize
+the transition but doesn't affect generation today. When VACE
+extension mode eventually supports end-frame targeting, the field
+is ready.
+
+### Import format
+
+The `loadStoryboard(jsonArray)` method accepts the same format and
+populates the timeline from it. Round-trip: export → import →
+export produces identical JSON.
+
+## Architecture
+
+### File structure
+
+```
+pict-editor-timeline/
+├── package.json
+├── .quackage.json
+├── source/
+│   ├── Pict-Section-Timeline.js           # Main export
+│   ├── views/
+│   │   ├── PictView-Timeline.js           # Container view: renders the full editor
+│   │   ├── PictView-Timeline-Cut.js       # Per-cut row: prompt, duration, image slots
+│   │   └── PictView-Timeline-Toolbar.js   # Top bar: add cut, import/export, total duration
+│   ├── providers/
+│   │   ├── Pict-Provider-TimelineDragDrop.js   # HTML5 drag-and-drop reordering
+│   │   └── Pict-Provider-TimelineOps.js        # Data mutations (add, remove, reorder, update)
+│   └── templates/
+│       ├── timeline-container.html
+│       ├── timeline-cut.html
+│       └── timeline-toolbar.html
+├── test/
+│   └── Pict-Timeline_tests.js
+└── docs/
+    └── README.md
+```
+
+### View hierarchy
+
+```
+PictView-Timeline (container)
+├── PictView-Timeline-Toolbar
+│   ├── [+ Add Cut] button
+│   ├── [Import JSON] button
+│   ├── [Export JSON] button
+│   └── Total duration display (sum of all cuts' target_seconds)
+│
+├── PictView-Timeline-Cut (repeated per cut, vertical list)
+│   ├── Drag handle (≡)
+│   ├── Cut number badge (#1, #2, ...)
+│   ├── Start frame image slot (drop zone / upload / paste)
+│   ├── Prompt textarea
+│   ├── Duration control (target_seconds, number input with +/- steppers)
+│   ├── End frame image slot (drop zone / upload / paste, optional)
+│   ├── [Duplicate] [Delete] buttons
+│   └── Collapse/expand toggle
+│
+└── Visual timeline strip (bottom, read-only)
+    └── Proportional-width color blocks per cut showing relative durations
+```
+
+### Provider pattern
+
+Following `pict-section-formeditor` exactly:
+
+**PictView-Timeline** (main view):
+- Extends `libPictView`
+- In constructor: creates `TimelineDragDrop` and `TimelineOps`
+  providers via `this.pict.addProvider()`
+- Stores the cut array in `this.pict.AppData.Timeline.Cuts`
+- Renders by iterating over cuts and emitting per-cut HTML
+- Exposes `getStoryboard()` and `loadStoryboard()` on `window`
+
+**Pict-Provider-TimelineDragDrop**:
+- Extends `libPictProvider`
+- Tracks `_DragState` with source cut index
+- Implements `onDragStart`, `onDragOver`, `onDrop`, `onDragEnd`
+- Uses top/bottom half detection for insert-before/insert-after
+- Calls `this._ParentTimeline.render()` after reorder
+
+**Pict-Provider-TimelineOps**:
+- Extends `libPictProvider`
+- `addCut(afterIndex)` — insert a new cut with defaults
+- `removeCut(index)` — remove and re-index
+- `duplicateCut(index)` — deep-copy + insert after
+- `updateCut(index, field, value)` — update a single field
+- `moveCut(fromIndex, toIndex)` — reorder (called by drag-drop)
+- Always calls `this._ParentTimeline.render()` after mutations
+
+### Image slot design
+
+Each cut has two image slots: start frame and end frame. The slots
+are generic drop zones that support three input methods:
+
+1. **Click to browse** — triggers a hidden `<input type="file">`
+2. **Drag-and-drop** — accepts image files dropped from Finder/Explorer
+3. **Paste** — accepts clipboard image data (Ctrl/Cmd+V when focused)
+
+When an image is provided via any method, the slot:
+- Shows a thumbnail preview (resized client-side for display)
+- Stores the image reference in the cut data
+
+**The image reference format depends on the host app's adapter:**
+
+| Host | start_image / end_image value |
+|---|---|
+| Standalone (no adapter) | Data URL (`data:image/png;base64,...`) |
+| retold-labs adapter | Materialized asset path (`/path/to/materialized/GUID/file.jpg`) |
+| CLI tool | Filesystem path (`./images/garden.jpg`) |
+
+The timeline editor ships a default adapter that uses data URLs. The
+host app overrides this by setting `options.ImageAdapter` to an object
+with:
+
+```javascript
+{
+    // Called when user drops/selects/pastes an image
+    onImageProvided: async (file, cutIndex, slot) => {
+        // Upload to storage, return a reference string
+        return "/path/to/stored/image.jpg";
+    },
+
+    // Called to render a thumbnail from a reference string
+    getThumbnailUrl: (reference) => {
+        // Return a URL the browser can display in an <img> tag
+        return reference; // file paths, data URLs, and http URLs all work
+    }
+}
+```
+
+### CSS approach
+
+Dark theme by default (matching retold-labs). All classes prefixed
+with `pet-` (Pict Editor Timeline). CSS injected via the PictView
+`CSS` option so it's included in the Pict CSS cascade without
+external stylesheets.
+
+Key visual elements:
+- Timeline container: vertical stack of cut cards
+- Cut card: horizontal layout with drag handle | image | prompt | duration | image
+- Image slots: dashed-border drop zones, thumbnail preview when populated
+- Duration strip: horizontal bar at the bottom, each cut proportional to its duration
+- Drag feedback: ghost opacity on drag source, insertion indicator on target
+
+### Default configuration
+
+```javascript
+module.exports = {
+    ViewIdentifier: 'Pict-Editor-Timeline',
+    DefaultRenderable: 'Timeline-Container',
+    DefaultDestinationAddress: '#PictEditorTimeline',
+    AutoInitialize: false,
+    AutoRender: false,
+    CSS: '/* ... */',
+    CSSHash: 'View-Editor-Timeline',
+    CSSPriority: 500,
+    DefaultCut: {
+        prompt: '',
+        target_seconds: 2,
+        start_image: '',
+        end_image: ''
+    },
+    MaxCuts: 50,
+    MinTargetSeconds: 0.5,
+    MaxTargetSeconds: 30,
+    ImageAdapter: null   // null = use built-in data-URL adapter
+};
+```
+
+## retold-labs integration (separate from pict-editor-timeline)
+
+When retold-labs imports the timeline editor, it provides:
+
+1. An `ImageAdapter` that wires image slots to the existing
+   asset-picker widget (upload → Parime → materialized path)
+2. A "Generate" button in the toolbar that serializes the timeline
+   to the storyboard format and POSTs it to the storyboard API
+3. A route (`#/timeline`) and nav item ("Timeline") in the sidebar
+
+This integration code lives in retold-labs, NOT in
+pict-editor-timeline. The library stays decoupled.
+
+```javascript
+// In Pict-Application-RetoldLabs.js:
+const libPictEditorTimeline = require('pict-editor-timeline');
+
+this.pict.addView('Timeline-Editor', Object.assign(
+    {},
+    libPictEditorTimeline.default_configuration,
+    {
+        DefaultDestinationAddress: '#RetoldLabs-View-Timeline',
+        ImageAdapter: {
+            onImageProvided: async (file, cutIndex, slot) => {
+                // Upload to Parime, return materialized path
+            },
+            getThumbnailUrl: (ref) => ref
+        }
+    }),
+    libPictEditorTimeline);
+```
+
+## Build and test
+
+### Build
+```bash
+npx quack build
+```
+Produces `dist/pict-editor-timeline.js` (UMD bundle) for direct
+`<script>` inclusion, plus the npm-requireable source tree.
+
+### Test
+```bash
+npm test
+```
+Mocha TDD tests covering:
+- Data model: add/remove/reorder/duplicate/update cuts
+- Export: getStoryboard() produces correct JSON
+- Import: loadStoryboard() round-trips cleanly
+- Duration math: total duration updates on add/remove/change
+- Validation: prompt required, target_seconds in range
+
+No browser tests in the library itself — the visual testing happens
+in retold-labs' browser integration suite after integration.
+
+## Implementation order
+
+1. **Scaffold**: package.json, .quackage.json, directory structure
+2. **Data model + ops provider**: cut CRUD, reorder, export/import
+3. **Unit tests**: data model round-trip, duration math
+4. **Container view + toolbar**: render shell, add/export buttons
+5. **Cut view**: prompt textarea, duration control, image slots
+6. **Drag-and-drop provider**: reorder cuts by dragging
+7. **Image adapter**: default data-URL adapter, slot thumbnails
+8. **Duration strip**: proportional-width visual timeline at bottom
+9. **CSS**: dark theme, drag feedback, responsive layout
+10. **retold-labs integration**: ImageAdapter, route, nav item, Generate button

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "pict-editor-timeline",
+	"version": "0.0.1",
+	"description": "Pict visual timeline editor for building multi-beat video storyboards. Add, reorder, and configure cuts with text prompts, durations, and optional start/end frame image slots. Exports clean JSON consumable by any downstream video generation system.",
+	"main": "source/Pict-Section-Timeline.js",
+	"scripts": {
+		"start": "node source/Pict-Section-Timeline.js",
+		"test": "npx mocha -u tdd --exit --timeout 5000 test/Pict-Timeline_tests.js",
+		"tests": "npx mocha -u tdd --exit --timeout 5000 -g",
+		"coverage": "npx nyc --reporter=lcov --reporter=text npm test",
+		"build": "npx quack build"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/stevenvelozo/pict-editor-timeline.git"
+	},
+	"author": "steven velozo <steven@velozo.com>",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/stevenvelozo/pict-editor-timeline/issues"
+	},
+	"homepage": "https://github.com/stevenvelozo/pict-editor-timeline#readme",
+	"dependencies": {
+		"pict-view": "^1.0.68",
+		"pict-provider": "^1.0.12"
+	},
+	"devDependencies": {
+		"fable": "^3.0.0",
+		"mocha": "^10.2.0",
+		"quackage": "^1.1.0"
+	}
+}

package/source/Pict-Section-Timeline.js

@@ -0,0 +1,24 @@
+/**
+ * pict-editor-timeline — Main Export
+ *
+ * Visual timeline editor for building multi-beat video storyboards.
+ * Exports the PictView-Timeline view class as the default export,
+ * plus individual provider classes for advanced usage.
+ *
+ * Usage:
+ *   const libTimeline = require('pict-editor-timeline');
+ *   pict.addView('MyTimeline', libTimeline.default_configuration, libTimeline);
+ *
+ * @author Steven Velozo <steven@velozo.com>
+ * @license MIT
+ */
+
+const libPictViewTimeline = require('./views/PictView-Timeline.js');
+
+// Default export: the main view class
+module.exports = libPictViewTimeline;
+
+// Re-export configuration and provider classes for advanced usage
+module.exports.default_configuration = libPictViewTimeline.default_configuration;
+module.exports.TimelineOpsProvider = require('./providers/Pict-Provider-TimelineOps.js');
+module.exports.TimelineDragDropProvider = require('./providers/Pict-Provider-TimelineDragDrop.js');

package/source/providers/Pict-Provider-TimelineDragDrop.js

@@ -0,0 +1,177 @@
+/**
+ * Pict Provider: Timeline Drag and Drop
+ *
+ * Handles HTML5 drag-and-drop reordering of cuts in the timeline.
+ * Follows the same pattern as pict-section-formeditor's
+ * Pict-Provider-FormEditorDragDrop: tracks drag state, detects
+ * insert position (before/after based on cursor Y), and delegates
+ * the actual array mutation to TimelineOps.moveCut().
+ *
+ * @author Steven Velozo <steven@velozo.com>
+ * @license MIT
+ */
+const libPictProvider = require('pict-provider');
+
+class PictProviderTimelineDragDrop extends libPictProvider
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'PictProviderTimelineDragDrop';
+
+		// Set by parent view after construction
+		this._ParentTimeline = null;
+
+		// Current drag state
+		this._DragState =
+		{
+			Active: false,
+			SourceIndex: -1,
+			TargetIndex: -1,
+			InsertPosition: 'after'  // 'before' | 'after'
+		};
+	}
+
+	/**
+	 * Called from ondragstart on a cut's drag handle.
+	 */
+	onDragStart(pEvent, pCutIndex)
+	{
+		this._DragState.Active = true;
+		this._DragState.SourceIndex = pCutIndex;
+
+		if (pEvent && pEvent.dataTransfer)
+		{
+			pEvent.dataTransfer.effectAllowed = 'move';
+			// Required for Firefox
+			pEvent.dataTransfer.setData('text/plain', String(pCutIndex));
+		}
+
+		if (pEvent && pEvent.currentTarget)
+		{
+			pEvent.currentTarget.classList.add('pet-dragging');
+		}
+	}
+
+	/**
+	 * Called from ondragover on each cut row. Detects whether the
+	 * cursor is in the top or bottom half to determine insert
+	 * position.
+	 */
+	onDragOver(pEvent, pCutIndex)
+	{
+		if (!this._DragState.Active)
+		{
+			return;
+		}
+
+		if (pEvent)
+		{
+			pEvent.preventDefault();
+		}
+
+		this._DragState.TargetIndex = pCutIndex;
+
+		// Detect top/bottom half for insert indicator
+		if (pEvent && pEvent.currentTarget)
+		{
+			let tmpRect = pEvent.currentTarget.getBoundingClientRect();
+			let tmpMidpoint = tmpRect.top + (tmpRect.height / 2);
+			this._DragState.InsertPosition = pEvent.clientY < tmpMidpoint ? 'before' : 'after';
+
+			// Visual feedback
+			pEvent.currentTarget.classList.remove('pet-drag-insert-before', 'pet-drag-insert-after');
+			pEvent.currentTarget.classList.add(
+				this._DragState.InsertPosition === 'before'
+					? 'pet-drag-insert-before'
+					: 'pet-drag-insert-after');
+		}
+	}
+
+	/**
+	 * Called from ondragleave on each cut row.
+	 */
+	onDragLeave(pEvent, pCutIndex)
+	{
+		if (pEvent && pEvent.currentTarget)
+		{
+			pEvent.currentTarget.classList.remove(
+				'pet-drag-insert-before',
+				'pet-drag-insert-after');
+		}
+	}
+
+	/**
+	 * Called from ondrop on each cut row.
+	 */
+	onDrop(pEvent, pCutIndex)
+	{
+		if (pEvent)
+		{
+			pEvent.preventDefault();
+		}
+
+		if (!this._DragState.Active)
+		{
+			return;
+		}
+
+		let tmpFrom = this._DragState.SourceIndex;
+		let tmpTo = pCutIndex;
+
+		// Adjust for insert position
+		if (this._DragState.InsertPosition === 'after')
+		{
+			tmpTo = tmpTo + 1;
+		}
+
+		// Adjust if moving downward (source removal shifts indices)
+		if (tmpFrom < tmpTo)
+		{
+			tmpTo = tmpTo - 1;
+		}
+
+		if (this._ParentTimeline && this._ParentTimeline._TimelineOps)
+		{
+			this._ParentTimeline._TimelineOps.moveCut(tmpFrom, tmpTo);
+		}
+
+		this._resetDragState();
+
+		// Re-render the timeline
+		if (this._ParentTimeline)
+		{
+			this._ParentTimeline.render();
+		}
+	}
+
+	/**
+	 * Called from ondragend on the drag handle (fires even if drop
+	 * was cancelled).
+	 */
+	onDragEnd(pEvent)
+	{
+		this._resetDragState();
+
+		// Clean up any lingering CSS classes
+		if (typeof document !== 'undefined')
+		{
+			let tmpEls = document.querySelectorAll('.pet-dragging, .pet-drag-insert-before, .pet-drag-insert-after');
+			for (let i = 0; i < tmpEls.length; i++)
+			{
+				tmpEls[i].classList.remove('pet-dragging', 'pet-drag-insert-before', 'pet-drag-insert-after');
+			}
+		}
+	}
+
+	_resetDragState()
+	{
+		this._DragState.Active = false;
+		this._DragState.SourceIndex = -1;
+		this._DragState.TargetIndex = -1;
+		this._DragState.InsertPosition = 'after';
+	}
+}
+
+module.exports = PictProviderTimelineDragDrop;
+module.exports.default_configuration = {};