@paramrig/web 0.1.0

package/dist/rigs/extended-types.d.ts

@@ -0,0 +1,184 @@
+import type { ParameterDef, ParamValue } from './types';
+export type ParameterBase = {
+    id: string;
+    label: string;
+    group: string;
+    description?: string;
+    hidden?: boolean;
+};
+export type Option = {
+    value: string;
+    label: string;
+    preview?: string;
+};
+export type Point = {
+    x: number;
+    y: number;
+};
+export type RadialZone = {
+    label: string;
+    start: number;
+    end: number;
+};
+export type RadialLayer = {
+    name: string;
+    color: string;
+    enabled: boolean;
+    points: Point[];
+};
+export type ResourceValue = {
+    id: string;
+    name: string;
+    mime: string;
+    size: number;
+};
+export type Gizmo2DValue = {
+    position: [number, number];
+    size: [number, number];
+    rotation: number;
+};
+export type Gizmo3DValue = {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+    mode: 'translate' | 'rotate' | 'scale';
+};
+export type TextureFrameValue = {
+    rect: [number, number, number, number];
+    rotation: number;
+};
+export type CameraValue = {
+    azimuth: number;
+    elevation: number;
+    distance: number;
+    fov: number;
+};
+export type ModulationValue = {
+    enabled: boolean;
+    mode: string;
+    rate: number;
+    phase: number;
+    amplitude: number;
+    offset: number;
+    attack: number;
+    hold: number;
+    release: number;
+    seed: number;
+};
+export type ValueSource = {
+    mode: 'local';
+} | {
+    mode: 'parameter';
+    source?: string;
+} | {
+    mode: 'expression';
+    expression?: string;
+} | {
+    mode: 'animation';
+} | {
+    mode: 'macro';
+    source?: string;
+    min: number;
+    max: number;
+} | {
+    mode: 'modulation';
+    shape: ModulationValue['mode'];
+    rate: number;
+    phase: number;
+    amplitude: number;
+    offset: number;
+    attack: number;
+    hold: number;
+    release: number;
+    seed: number;
+} | {
+    mode: 'blend';
+    source?: string;
+    amount?: number;
+    from: number;
+    to: number;
+};
+export type ExtendedParameter = ParameterBase & ({
+    kind: 'vector';
+    defaultValue: number[];
+    axes: string[];
+    min: number;
+    max: number;
+    step: number;
+    unit?: string;
+    view?: 'fields' | 'xy' | 'dimensions' | 'direction' | 'rotation' | 'anchor';
+    proportional?: boolean;
+    linkLabel?: string;
+} | {
+    kind: 'range';
+    defaultValue: number[];
+    min: number;
+    max: number;
+    step: number;
+    unit?: string;
+} | {
+    kind: 'text';
+    defaultValue: string;
+    multiline?: boolean;
+    maxLength?: number;
+} | {
+    kind: 'multiselect';
+    defaultValue: string[];
+    options: Option[];
+} | {
+    kind: 'palette';
+    defaultValue: string[];
+    maxItems?: number;
+} | {
+    kind: 'points';
+    defaultValue: Point[];
+    view?: 'curve' | 'ramp' | 'path';
+    min?: number;
+    max?: number;
+} | {
+    kind: 'radial';
+    defaultValue: RadialLayer[];
+    zones?: RadialZone[];
+    maxLayers?: number;
+} | {
+    kind: 'resource';
+    defaultValue: ResourceValue | null;
+    accept: string;
+    view?: 'image' | 'texture' | 'svg' | 'font' | 'model' | 'environment';
+    maxMB?: number;
+} | {
+    kind: 'gizmo2d';
+    defaultValue: Gizmo2DValue;
+} | {
+    kind: 'gizmo3d';
+    defaultValue: Gizmo3DValue;
+} | {
+    kind: 'textureFrame';
+    defaultValue: TextureFrameValue;
+} | {
+    kind: 'camera';
+    defaultValue: CameraValue;
+} | {
+    kind: 'group';
+    defaultValue: Record<string, ParamValue>;
+    fields: ParameterDef[];
+} | {
+    kind: 'list';
+    defaultValue: ParamValue[];
+    item: ParameterDef;
+    maxItems?: number;
+} | {
+    kind: 'action';
+    defaultValue: number;
+    action: 'set' | 'randomize' | 'reset' | 'trigger';
+    targets?: string[];
+    values?: Record<string, ParamValue>;
+} | {
+    kind: 'preset';
+    defaultValue: string;
+    options: {
+        value: string;
+        label: string;
+        values: Record<string, ParamValue>;
+    }[];
+});

package/dist/rigs/types.d.ts

@@ -0,0 +1,199 @@
+export type Vec2 = [number, number];
+export type BezierCurve = {
+    type: 'cubic-bezier';
+    p0: Vec2;
+    p1: Vec2;
+    p2: Vec2;
+    p3: Vec2;
+};
+export type GradientStop = {
+    t: number;
+    color: string;
+};
+export type ParamValue = number | string | boolean | null | BezierCurve | GradientStop[] | ParamValue[] | {
+    [key: string]: ParamValue;
+};
+export type NumberParam = {
+    kind: 'number';
+    id: string;
+    label: string;
+    group: string;
+    min: number;
+    max: number;
+    step: number;
+    unit?: string;
+    /** Display-only unit conversions. Stored values remain in the base unit. */
+    units?: {
+        value: string;
+        label: string;
+        factor: number;
+        step?: number;
+    }[];
+    defaultValue: number;
+    sliderMin?: number;
+    sliderMax?: number;
+    /** 'bar' is the default measured view: the field itself is the track, filled to the value. */
+    view?: 'field' | 'stepper' | 'bar' | 'knob' | 'angle' | 'seed';
+    scale?: 'linear' | 'log';
+    stops?: number[];
+    readOnly?: boolean;
+    role?: 'duration' | 'playhead';
+    defaultSource?: import('./extended-types').ValueSource;
+    hidden?: boolean;
+};
+export type ColorParam = {
+    kind: 'color';
+    id: string;
+    label: string;
+    group: string;
+    defaultValue: string;
+    alpha?: boolean;
+    channels?: boolean;
+    hidden?: boolean;
+};
+export type SelectParam = {
+    kind: 'select';
+    id: string;
+    label: string;
+    group: string;
+    options: {
+        value: string;
+        label: string;
+        preview?: string;
+    }[];
+    defaultValue: string;
+    appliesToTracks?: boolean;
+    view?: 'search' | 'visual' | 'font';
+    hidden?: boolean;
+};
+export type CurveParam = {
+    kind: 'curve';
+    id: string;
+    label: string;
+    group: string;
+    defaultValue: BezierCurve;
+    hidden?: boolean;
+};
+export type SwitchParam = {
+    kind: 'switch';
+    id: string;
+    label: string;
+    group: string;
+    defaultValue: boolean;
+    hidden?: boolean;
+};
+export type GradientParam = {
+    kind: 'gradient';
+    id: string;
+    label: string;
+    group: string;
+    defaultValue: GradientStop[];
+    hidden?: boolean;
+};
+export type ParameterDef = NumberParam | ColorParam | SelectParam | CurveParam | SwitchParam | GradientParam | import('./extended-types').ExtendedParameter;
+export type Keyframe = {
+    id?: string;
+    time: number;
+    value: number;
+    easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'step';
+};
+export type KeyframeRef = {
+    paramId: string;
+    id: string;
+};
+export type LoopRange = {
+    start: number;
+    end: number;
+};
+export type AnimTrack = {
+    paramId: string;
+    interpolation: 'linear' | 'step';
+    keyframes: Keyframe[];
+};
+export type AnimationDef = {
+    duration: number;
+    fps: number;
+    loop: boolean;
+    tracks: AnimTrack[];
+};
+export type ParamGroup = {
+    id: string;
+    label: string;
+    /** Optional secondary inspector tab. Groups without one remain visible in every tab. */
+    tab?: string;
+    defaultOpen?: boolean;
+};
+export type InspectorCategory = {
+    id: string;
+    label: string;
+};
+export type RendererKind = 'svg' | 'three' | 'html' | 'vector' | 'scene' | 'web';
+export type RigManifest = {
+    id: string;
+    name: string;
+    summary: string;
+    description: string;
+    renderer: RendererKind;
+    rendererLabel: string;
+    collection: 'examples' | 'project';
+    /** Storybook-style path. Folders are `/` segments; the leaf is `name`. */
+    title: string;
+    sourceFile: string;
+    tags: string[];
+    /** Optional second-level navigation for rigs with several families of controls. */
+    inspectorCategories?: InspectorCategory[];
+    groups: ParamGroup[];
+    parameters: ParameterDef[];
+    animation?: AnimationDef;
+};
+export type Snapshot = {
+    id: string;
+    name: string;
+    createdAt: string;
+    values: Record<string, ParamValue>;
+    valueSources?: Record<string, import('./extended-types').ValueSource>;
+    tracks?: AnimTrack[];
+    loop?: boolean;
+    loopRange?: LoopRange | null;
+    duration?: number;
+};
+export type ExportDocument = {
+    version: 1;
+    rigId: string;
+    name: string;
+    exportedAt: string;
+    values: Record<string, ParamValue>;
+    valueSources: Record<string, import('./extended-types').ValueSource>;
+    animation?: {
+        duration: number;
+        fps: number;
+        loop: boolean;
+        playhead: number;
+        tracks: AnimTrack[];
+        loopRange?: LoopRange | null;
+    };
+};
+export type StoredDraft = {
+    version: 1;
+    rigId: string;
+    values: Record<string, ParamValue>;
+    valueSources?: Record<string, import('./extended-types').ValueSource>;
+    snapshots: Snapshot[];
+    compare: 'original' | 'current';
+    activeSnapshotId: string | null;
+    playhead: number;
+    loop: boolean;
+    tracks?: AnimTrack[];
+    loopRange?: LoopRange | null;
+    duration?: number;
+};
+export type PanelPrefs = {
+    version: 1;
+    navWidth: number;
+    inspectorWidth: number;
+    timelineHeight: number;
+    navCollapsed: boolean;
+    navCompact: boolean;
+    inspectorCollapsed: boolean;
+    timelineCollapsed: boolean;
+};

package/dist/web/contracts.d.ts

@@ -0,0 +1,287 @@
+import type { ParameterDef, ParamGroup, ParamValue } from '../rigs/types.ts';
+export declare const WEB_PROTOCOL = 1;
+export declare const WEB_CHANNEL = "paramrig.web";
+export type Values = Record<string, ParamValue>;
+export type Point = {
+    x: number;
+    y: number;
+};
+export type Rect = Point & {
+    width: number;
+    height: number;
+};
+export type TargetKey = {
+    id: string;
+    instance?: string;
+};
+export type WebBinding = {
+    paramId: string;
+    scope: 'global' | 'page' | 'element';
+    pageId?: string;
+    target?: TargetKey;
+    kind: 'css-variable' | 'style' | 'adapter';
+    property: string;
+    unit?: string;
+    source?: string;
+};
+export type WebProjectManifest = {
+    version: 1;
+    id: string;
+    name: string;
+    revision: string;
+    origin: string;
+    pages: {
+        id: string;
+        name: string;
+        path: string;
+    }[];
+    groups: ParamGroup[];
+    parameters: ParameterDef[];
+    bindings: WebBinding[];
+};
+export type WebTarget = {
+    key: string;
+    stable?: TargetKey;
+    selector: string;
+    fingerprint: string;
+    label: string;
+    tag: string;
+    source?: string;
+    pageId: string;
+    rect: Rect;
+    clip?: Rect;
+    ancestors: {
+        key: string;
+        label: string;
+        stable?: TargetKey;
+    }[];
+    status: 'resolved' | 'provisional' | 'missing' | 'ambiguous';
+    /** How many of the manifest's controls reach this element. Absent means none were counted. */
+    controls?: number;
+};
+/** Colours the host hands the page so the overlay follows the workbench theme. */
+export type WebChrome = {
+    outline: string;
+    chip: string;
+    chipText: string;
+};
+export type WebContext = {
+    pageId: string;
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    scroll: Point;
+    scrollers: {
+        target: WebTarget;
+        x: number;
+        y: number;
+    }[];
+};
+export type MarkTool = 'note' | 'arrow' | 'rectangle' | 'ellipse' | 'highlight' | 'pen';
+export type WebMark = {
+    id: string;
+    tool: MarkTool;
+    color: string;
+    width: number;
+    points: Point[];
+    /** Element marks use fractions of its box; free marks use document CSS pixels. */
+    targetKey?: string;
+    pageId: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+};
+export type Capture = {
+    id: string;
+    kind: 'dom' | 'screen';
+    createdAt: string;
+    status: 'ready' | 'failed';
+    file?: string;
+    note: string;
+    /** Offline recovery only; removed once the capture has been saved to disk. */
+    dataUrl?: string;
+};
+export type TicketStatus = 'draft' | 'todo' | 'review' | 'validated' | 'clarification';
+export type WebTicket = {
+    id: string;
+    /** The number a person sees. Assigned once and never reused, so removals do not renumber. */
+    number?: number;
+    comment: string;
+    status: TicketStatus;
+    revision: string;
+    createdAt: string;
+    context: WebContext;
+    targets: WebTarget[];
+    marks: WebMark[];
+    captures: Capture[];
+    batchId?: string;
+    response?: string;
+    responseRevision?: string;
+};
+export type ValueConflict = {
+    id: string;
+    before?: ParamValue;
+    chosen: ParamValue;
+    source?: ParamValue;
+    removed: boolean;
+};
+export type WebSnapshot = {
+    id: string;
+    name: string;
+    revision: string;
+    values: Values;
+};
+export type WebDraft = {
+    version: 1;
+    projectId: string;
+    sourceRevision: string;
+    sourceValues: Values;
+    values: Values;
+    tickets: WebTicket[];
+    snapshots: WebSnapshot[];
+    conflicts: ValueConflict[];
+    handledResponses: string[];
+};
+export type FeedbackBatch = {
+    version: 1;
+    id: string;
+    projectId: string;
+    sourceRevision: string;
+    createdAt: string;
+    values: Values;
+    changes: {
+        paramId: string;
+        label: string;
+        before: ParamValue;
+        after: ParamValue;
+        bindings: WebBinding[];
+    }[];
+    tickets: WebTicket[];
+};
+export type AgentResponse = {
+    version: 1;
+    id: string;
+    batchId: string;
+    projectId: string;
+    sourceRevision: string;
+    resultRevision: string;
+    createdAt: string;
+    tickets: {
+        id: string;
+        status: 'implemented' | 'needs-info';
+        message: string;
+    }[];
+    summary: string;
+};
+export type HostCommand = {
+    type: 'hello';
+    projectId: string;
+} | {
+    type: 'configure';
+    mode: 'browse' | 'select' | 'annotate';
+    tool: MarkTool;
+    color: string;
+    targets: WebTarget[];
+    marks: WebMark[];
+    activeTarget?: string;
+    activeTargets?: string[];
+    activeMarks?: string[];
+    displayScale?: number;
+    chrome?: WebChrome;
+} | {
+    type: 'values';
+    values: Values;
+    source: boolean;
+} | {
+    type: 'select';
+    target: WebTarget;
+} | {
+    type: 'reveal-target';
+    target: WebTarget;
+} | {
+    type: 'restore-context';
+    context: WebContext;
+} | {
+    type: 'navigate';
+    path: string;
+} | {
+    type: 'capture';
+    requestId: string;
+};
+export type SDKEvent = {
+    type: 'ready';
+    instanceId: string;
+    manifest: WebProjectManifest;
+    sourceValues: Values;
+    context: WebContext;
+} | {
+    type: 'scene';
+    context: WebContext;
+    targets: WebTarget[];
+    page?: WebTarget[];
+} | {
+    type: 'selection';
+    target: WebTarget;
+    additive: boolean;
+} | {
+    type: 'comment';
+    target: WebTarget;
+} | {
+    type: 'exit-tool';
+} | {
+    type: 'mark';
+    mark: WebMark;
+    target?: WebTarget;
+    context: WebContext;
+} | {
+    type: 'capture';
+    requestId: string;
+    dataUrl?: string;
+    error?: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'history';
+    direction: 'undo' | 'redo';
+};
+export type Envelope<T> = {
+    channel: typeof WEB_CHANNEL;
+    version: number;
+    sessionId: string;
+    payload: T;
+};
+/**
+ * The frame the SDK sends the moment it starts listening, before any session exists.
+ * It carries no session ID, so it is deliberately not an envelope: the host answers it with
+ * `hello` and every later message is checked against the session that handshake opened.
+ */
+export type SDKAnnouncement = {
+    channel: typeof WEB_CHANNEL;
+    version: number;
+    type: 'sdk-present';
+    projectId: string;
+    instanceId: string;
+};
+export declare function record(value: unknown): value is Record<string, unknown>;
+export declare function safeId(value: unknown): value is string;
+export declare function isValues(value: unknown): value is Values;
+export declare function parseManifest(value: unknown): WebProjectManifest;
+export declare function isTarget(v: unknown): v is WebTarget;
+export declare function isChrome(v: unknown): v is WebChrome;
+export declare function isContext(v: unknown): v is WebContext;
+export declare function isMark(v: unknown): v is WebMark;
+export declare function isTicket(v: unknown): v is WebTicket;
+export declare function isDraft(v: unknown): v is WebDraft;
+export declare function isBatch(v: unknown): v is FeedbackBatch;
+export declare function isResponse(v: unknown): v is AgentResponse;
+export declare function envelope<T>(sessionId: string, payload: T): Envelope<T>;
+export declare function announcement(projectId: string, instanceId: string): SDKAnnouncement;
+export declare function isAnnouncement(v: unknown): v is SDKAnnouncement;
+export declare function isEnvelope(v: unknown): v is Envelope<Record<string, unknown>>;
+export declare function isCommand(p: Record<string, unknown>): boolean;
+export declare function isEvent(p: Record<string, unknown>): boolean;

package/dist/web/geometry.d.ts

@@ -0,0 +1,5 @@
+import type { Point, Rect, WebMark, WebTarget } from './contracts.ts';
+export declare function markPoints(mark: WebMark, targets: WebTarget[], scroll: Point): Point[] | null;
+export declare function storedPoint(point: Point, target: WebTarget | undefined, scroll: Point): Point;
+export declare function bounds(points: Point[]): Rect;
+export declare function pathForMark(mark: WebMark, points: Point[]): string;

package/dist/web/sdk.d.ts

@@ -0,0 +1,20 @@
+import { type WebProjectManifest } from './contracts.ts';
+import type { ParamValue } from '../rigs/types.ts';
+export { parseManifest } from './contracts.ts';
+export type { WebProjectManifest, WebBinding, WebTarget, FeedbackBatch, AgentResponse } from './contracts.ts';
+export type { ParameterDef, ParamValue } from '../rigs/types.ts';
+export type WebAdapter = {
+    read: () => ParamValue;
+    apply: (value: ParamValue) => void;
+    restore: () => void;
+};
+export type ConnectWebOptions = {
+    manifest: WebProjectManifest;
+    hostOrigin?: string | readonly string[];
+    adapters?: Record<string, WebAdapter>;
+};
+/** Where the workbench runs by default. Both aliases, because a browser reaches it by either. */
+export declare const DEFAULT_HOST_ORIGINS: readonly string[];
+export declare function connectWeb({ manifest: rawManifest, hostOrigin, adapters }: ConnectWebOptions): {
+    dispose(): void;
+};