@bitsnbobs/starch 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,273 @@
+# starch
+
+Animated diagram library for documenting application internals. Define objects and keyframe animations with a concise DSL or programmatic API, and render interactive SVG diagrams in React apps or any webpage.
+
+> **Note:** This entire project — code, architecture, and documentation — was built agentically using [Claude Code](https://claude.com/claude-code). It is under active development as an experiment in agentic software engineering. The library is at version 0.0.1 and the API may change.
+
+## Try It — Interactive Playground
+
+The fastest way to start is the built-in playground. It gives you a live editor alongside the rendered diagram with playback controls, so you can experiment with the DSL in real time.
+
+```bash
+git clone https://github.com/zummed/starch.git
+cd starch
+npm install
+npm run dev
+```
+
+This opens a split-pane view with a CodeMirror editor on the left, the animated SVG canvas on the right, and a timeline with play/pause/seek/speed controls at the bottom. Several built-in examples (state machine, data pipeline, container layout, path motion) are available from a dropdown to get started.
+
+The `Editor` and `Timeline` components used in the playground are exported from the library, so you can build your own editor experiences with them.
+
+## Install
+
+```bash
+npm install starch
+```
+
+Requires React 18 or 19 as a peer dependency.
+
+## Usage
+
+### React
+
+```tsx
+import { Diagram } from 'starch';
+
+const dsl = `{
+  objects: [
+    { box: "server", at: [200, 100], size: [120, 50], colour: "#34d399", text: "Server" },
+    { box: "client", at: [200, 250], size: [120, 50], colour: "#22d3ee", text: "Client" },
+    { line: "req", from: "client", to: "server", colour: "#fbbf24", label: "request" },
+  ],
+  animate: {
+    duration: 3,
+    keyframes: {
+      req: [[1.5, "progress", 1, "easeInOut"]],
+      server: [[1.5, "scale", 1.1], [2, "scale", 1, "easeOutBack"]],
+    }
+  }
+}`;
+
+function App() {
+  return <Diagram dsl={dsl} autoplay />;
+}
+```
+
+### Any Webpage (No React Required)
+
+Include the standalone embed bundle and use the `<starch-diagram>` custom element:
+
+```html
+<script src="https://unpkg.com/starch/dist/starch-embed.iife.js"></script>
+
+<starch-diagram autoplay speed="1">
+{
+  objects: [
+    { box: "server", at: [200, 100], size: [120, 50], colour: "#34d399", text: "Server" },
+    { box: "client", at: [200, 250], size: [120, 50], colour: "#22d3ee", text: "Client" },
+    { line: "req", from: "client", to: "server", colour: "#fbbf24", label: "request" },
+  ],
+  animate: {
+    duration: 3,
+    keyframes: {
+      req: [[1.5, "progress", 1, "easeInOut"]],
+      server: [[1.5, "scale", 1.1], [2, "scale", 1, "easeOutBack"]],
+    }
+  }
+}
+</starch-diagram>
+```
+
+The embed bundle is self-contained (~100KB gzip) with React bundled in.
+
+## DSL
+
+Diagrams are defined in a JSON5-based format with these object types:
+
+- **box** — rectangle with optional text, rounded corners, fill
+- **circle** — circle with radius
+- **label** — standalone text
+- **table** — rows and columns
+- **line** — connects two objects with optional label, bend, and dashing
+- **path** — arbitrary point sequence with spline curves
+- **group** — container with flex-like layout (direction, gap, padding)
+
+### Animation
+
+Keyframes target any object property at a given time with an optional easing. Properties that the user explicitly sets on the object definition are automatically used as the starting value, so you only need to specify the destination:
+
+```
+// A box defined with at: [100, 200]
+keyframes: {
+  myBox: [
+    [2, "x", 300, "easeOutBack"],  // slides from x=100 (the defined value) to 300
+  ]
+}
+```
+
+Supported easings: `linear`, `easeIn`, `easeOut`, `easeInOut`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeOutBack`, `easeInBack`, `bounce`, `elastic`, `spring`, `snap`, `step`.
+
+Chapters define named time markers for navigation:
+
+```
+chapters: [
+  [0, "intro", "Introduction"],
+  [3, "demo", "Live Demo"],
+]
+```
+
+## API
+
+### `<Diagram>` Component
+
+```tsx
+<Diagram
+  dsl={string}        // DSL string
+  scene={Scene}       // or a programmatic Scene instance
+  autoplay={boolean}
+  speed={number}
+  debug={boolean}
+  onEvent={(e) => {}} // chapter enter/exit, animation end/loop
+/>
+```
+
+Accepts a `ref` exposing `DiagramHandle`:
+
+```tsx
+const ref = useRef<DiagramHandle>(null);
+
+ref.current.play();
+ref.current.pause();
+ref.current.seek(2.5);
+ref.current.nextChapter();
+ref.current.prevChapter();
+ref.current.goToChapter('step-2');
+```
+
+### `useDiagram` Hook
+
+For custom layouts and full state access:
+
+```tsx
+const diagram = useDiagram({ dsl, autoplay: true });
+
+// State
+diagram.time        // current time
+diagram.duration    // total duration
+diagram.playing     // playback state
+diagram.speed       // playback speed
+diagram.chapters    // chapter definitions
+diagram.activeChapter // currently active chapter
+
+// Methods
+diagram.play()
+diagram.pause()
+diagram.seek(time)
+diagram.nextChapter()
+diagram.prevChapter()
+diagram.goToChapter(id)
+
+// Rendering data
+diagram.objects       // parsed scene objects
+diagram.animatedProps // current animated properties per object
+diagram.renderOrder   // depth-sorted render order
+```
+
+### `Scene` (Programmatic API)
+
+```tsx
+import { Scene, Diagram } from 'starch';
+
+const scene = new Scene();
+scene.box('server', { x: 200, y: 100, w: 120, h: 50, text: 'Server', stroke: '#34d399' });
+scene.line('conn', { from: 'client', to: 'server', stroke: '#fbbf24' });
+
+const anim = scene.animate({ duration: 5 });
+anim.at(0, 'conn', 'progress', 0);
+anim.at(2, 'conn', 'progress', 1, 'easeInOut');
+anim.chapter(0, 'start', 'Start');
+
+<Diagram scene={scene} autoplay />
+```
+
+### `<starch-diagram>` Custom Element
+
+Attributes: `autoplay`, `speed`, `debug`, `src`
+
+```html
+<!-- Inline DSL -->
+<starch-diagram autoplay>
+  ...DSL here...
+</starch-diagram>
+
+<!-- External DSL file -->
+<starch-diagram src="/diagrams/my-diagram.starch" autoplay></starch-diagram>
+```
+
+JavaScript interaction:
+
+```js
+const el = document.querySelector('starch-diagram');
+
+// Control
+el.play();
+el.pause();
+el.seek(2.5);
+el.goToChapter('step-2');
+
+// Read state
+el.time;          // current time
+el.duration;      // total duration
+el.playing;       // boolean
+el.chapters;      // array
+
+// Events
+el.addEventListener('starch:chapterenter', (e) => {
+  console.log('Entered chapter:', e.detail.chapter);
+});
+el.addEventListener('starch:chapterexit', (e) => { ... });
+el.addEventListener('starch:event', (e) => { ... });
+```
+
+## MkDocs Integration
+
+For MkDocs sites, starch can render fenced code blocks as live diagrams.
+
+1. Add the scripts to your `mkdocs.yml`:
+
+```yaml
+extra_javascript:
+  - https://unpkg.com/starch/dist/starch-embed.iife.js
+  - js/starch-init.js
+```
+
+2. Copy `docs/mkdocs-snippet.js` to your MkDocs `docs/js/starch-init.js`.
+
+3. Use fenced code blocks in your markdown:
+
+````markdown
+```starch
+{
+  objects: [
+    { box: "api", at: [200, 100], size: [100, 50], colour: "#34d399", text: "API" }
+  ],
+  animate: { duration: 3 }
+}
+```
+````
+
+The snippet finds `language-starch` code blocks and replaces them with live `<starch-diagram>` elements.
+
+## Development
+
+```bash
+npm run dev          # Start dev server with playground
+npm run build        # Build React library
+npm run build:embed  # Build standalone embed
+npm run build:all    # Build both
+```
+
+## License
+
+ISC

package/dist/components/Diagram.d.ts

@@ -0,0 +1,40 @@
+import { SceneObject, DiagramHandle, Chapter, StarchEvent } from '../core/types';
+import { Scene } from '../core/Scene';
+export interface DiagramProps {
+    scene?: Scene;
+    dsl?: string;
+    autoplay?: boolean;
+    speed?: number;
+    debug?: boolean;
+    onChapterEnter?: (event: StarchEvent) => void;
+    onChapterExit?: (event: StarchEvent) => void;
+    onEvent?: (event: StarchEvent) => void;
+}
+/**
+ * Hook version of Diagram for full layout control.
+ */
+export declare function useDiagram(props: DiagramProps): {
+    time: number;
+    duration: number;
+    playing: boolean;
+    speed: number;
+    chapters: Chapter[];
+    activeChapter: Chapter | undefined;
+    objects: Record<string, SceneObject<import('..').ObjectType>>;
+    animatedProps: Record<string, Record<string, unknown>>;
+    renderOrder: [string, SceneObject<import('..').ObjectType>][];
+    pct: number;
+    seek: (t: number) => void;
+    setPlaying: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    setSpeed: import('react').Dispatch<import('react').SetStateAction<number>>;
+    play: () => void;
+    pause: () => void;
+    nextChapter: () => void;
+    prevChapter: () => void;
+    goToChapter: (id: string) => void;
+};
+/**
+ * Self-contained Diagram component with SVG canvas.
+ */
+export declare const Diagram: import('react').ForwardRefExoticComponent<DiagramProps & import('react').RefAttributes<DiagramHandle>>;
+//# sourceMappingURL=Diagram.d.ts.map

package/dist/components/Diagram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Diagram.d.ts","sourceRoot":"","sources":["../../src/components/Diagram.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAY,WAAW,EAAE,MAAM,eAAe,CAAC;AAChG,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAOtC,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAC9C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACxC;AAiOD;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY;;;;;;;;;;;cAhItC,MAAM;;;;;;;sBA0BL,MAAM;EAwGd;AAED;;GAEG;AACH,eAAO,MAAM,OAAO,wGA2BlB,CAAC"}

package/dist/components/Editor.d.ts

@@ -0,0 +1,9 @@
+interface EditorProps {
+    value: string;
+    onChange: (value: string) => void;
+    parseError?: string | null;
+    width?: number;
+}
+export declare function Editor({ value, onChange, parseError, width }: EditorProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=Editor.d.ts.map

package/dist/components/Editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Editor.d.ts","sourceRoot":"","sources":["../../src/components/Editor.tsx"],"names":[],"mappings":"AAYA,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,MAAM,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAW,EAAE,EAAE,WAAW,2CAkG/E"}

package/dist/components/Timeline.d.ts

@@ -0,0 +1,15 @@
+import { Chapter } from '../core/types';
+interface TimelineProps {
+    time: number;
+    duration: number;
+    playing: boolean;
+    speed: number;
+    chapters?: Chapter[];
+    onSeek: (time: number) => void;
+    onTogglePlay: () => void;
+    onRestart: () => void;
+    onSpeedChange: (speed: number) => void;
+}
+export declare function Timeline({ time, duration, playing, speed, chapters, onSeek, onTogglePlay, onRestart, onSpeedChange, }: TimelineProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=Timeline.d.ts.map

package/dist/components/Timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timeline.d.ts","sourceRoot":"","sources":["../../src/components/Timeline.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAI7C,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,wBAAgB,QAAQ,CAAC,EACvB,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,KAAK,EACL,QAAa,EACb,MAAM,EACN,YAAY,EACZ,SAAS,EACT,aAAa,GACd,EAAE,aAAa,2CA4Ff"}

package/dist/core/Scene.d.ts

@@ -0,0 +1,47 @@
+import { SceneObject, AnimConfig, BoxProps, CircleProps, LabelProps, TableProps, LineProps, PathProps, GroupProps, EasingName, Chapter, StarchEvent, StarchEventType, StarchEventHandler } from './types';
+declare class AnimationBuilder {
+    private config;
+    constructor(config: AnimConfig);
+    at(time: number, target: string, prop: string, value: number | string | boolean, easing?: EasingName): this;
+    chapter(time: number, id: string, title: string, description?: string): this;
+}
+export declare class Scene {
+    private _objects;
+    private _animConfig;
+    private _listeners;
+    box(id: string, props: Partial<BoxProps> & {
+        w?: number;
+        h?: number;
+    }): this;
+    circle(id: string, props: Partial<CircleProps> & {
+        r?: number;
+    }): this;
+    label(id: string, props: Partial<LabelProps> & {
+        text: string;
+    }): this;
+    table(id: string, props: Partial<TableProps> & {
+        cols: string[];
+    }): this;
+    line(id: string, props: Partial<LineProps>): this;
+    path(id: string, props: Partial<PathProps> & {
+        points: Array<{
+            x: number;
+            y: number;
+        }>;
+    }): this;
+    group(id: string, props: Partial<GroupProps> & {
+        children?: string[];
+    }): this;
+    animate(opts: {
+        duration: number;
+        loop?: boolean;
+    }): AnimationBuilder;
+    on(type: StarchEventType, handler: StarchEventHandler): this;
+    off(type: StarchEventType, handler: StarchEventHandler): this;
+    emit(event: StarchEvent): void;
+    getObjects(): Record<string, SceneObject>;
+    getAnimConfig(): AnimConfig;
+    getChapters(): Chapter[];
+}
+export {};
+//# sourceMappingURL=Scene.d.ts.map

package/dist/core/Scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scene.d.ts","sourceRoot":"","sources":["../../src/core/Scene.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,UAAU,EACV,OAAO,EACP,WAAW,EACX,eAAe,EACf,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAIjB,cAAM,gBAAgB;IACpB,OAAO,CAAC,MAAM,CAAa;gBAEf,MAAM,EAAE,UAAU;IAI9B,EAAE,CACA,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAChC,MAAM,CAAC,EAAE,UAAU,GAClB,IAAI;IAWP,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;CAI7E;AAED,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,WAAW,CAKjB;IACF,OAAO,CAAC,UAAU,CAA4D;IAI9E,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAO5E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG;QAAE,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAOtE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAOtE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI;IAOxE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI;IAOjD,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG;QAAE,MAAM,EAAE,KAAK,CAAC;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GAAG,IAAI;IAO/F,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI;IAkB7E,OAAO,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,gBAAgB;IAQrE,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAQ5D,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAK7D,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAM9B,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;IAKzC,aAAa,IAAI,UAAU;IAI3B,WAAW,IAAI,OAAO,EAAE;CAGzB"}

package/dist/core/colours.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolve a colour string (named colour or #rrggbb) to hex.
+ */
+export declare function resolveColour(input: string): string;
+/**
+ * Derive a dark-themed fill colour from a stroke colour.
+ * Produces a near-black fill with a subtle hue tint.
+ */
+export declare function deriveFill(hex: string): string;
+/**
+ * Resolve the `colour` shortcut into fill and stroke values.
+ * Returns { fill, stroke } where colour is resolved to hex,
+ * fill is derived (duller shade), and explicit fill/stroke override.
+ */
+export declare function resolveColourShortcut(props: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=colours.d.ts.map

package/dist/core/colours.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colours.d.ts","sourceRoot":"","sources":["../../src/core/colours.ts"],"names":[],"mappings":"AA6FA;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUnD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBzB"}