@inneranimalmedia/agentsam-sdk 2.6.10 → 2.6.11

package/packages/agentsam-workbench/src/manufacturing/PreflightIndicator.tsx

@@ -0,0 +1,203 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+export type PreflightStatus =
+  | 'ready'
+  | 'ready_with_warning'
+  | 'ready_with_transform'
+  | 'prepared_for_digitization'
+  | 'needs_variant'
+  | 'unsupported';
+
+export interface PreflightIssueView {
+  code: string;
+  message: string;
+  action?: string | null;
+}
+
+export interface PreflightIndicatorProps {
+  status: PreflightStatus;
+  effectivePpi?: number | null;
+  readyPpi?: number | null;
+  minimumPpi?: number | null;
+  issues?: readonly PreflightIssueView[];
+  actions?: readonly string[];
+  onAction?: (action: string) => void;
+  compact?: boolean;
+  title?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const STATUS_COPY: Record<PreflightStatus, { label: string; tone: string }> = {
+  ready: { label: 'Production ready', tone: 'ready' },
+  ready_with_warning: { label: 'Usable with warning', tone: 'warning' },
+  ready_with_transform: { label: 'Quick fix available', tone: 'transform' },
+  prepared_for_digitization: { label: 'Prepared for digitization', tone: 'handoff' },
+  needs_variant: { label: 'Needs another asset variant', tone: 'error' },
+  unsupported: { label: 'Unsupported for this process', tone: 'error' },
+};
+
+const ACTION_LABELS: Record<string, string> = {
+  trim_alpha: 'Auto-Crop Alpha',
+  vectorize_monochrome: 'Convert to Monochrome Vector',
+  scale_to_safe_zone: 'Scale to Fit Safe Zone',
+  normalize_svg: 'Normalize SVG',
+  outline_text: 'Outline Text',
+  lossless_optimize: 'Optimize Losslessly',
+};
+
+function labelForAction(action: string) {
+  if (ACTION_LABELS[action]) return ACTION_LABELS[action];
+  if (action.startsWith('normalize_color_space:')) return 'Normalize Color';
+  if (action.startsWith('convert:')) return 'Convert Format';
+  if (action.startsWith('rasterize:')) return 'Rasterize for Print';
+  return action
+    .replace(/[:_-]+/g, ' ')
+    .replace(/\b\w/g, (value) => value.toUpperCase());
+}
+
+function qualityPercent(
+  effectivePpi: number | null | undefined,
+  readyPpi: number | null | undefined,
+) {
+  if (!effectivePpi || !readyPpi) return null;
+  return Math.max(0, Math.min(100, (effectivePpi / readyPpi) * 100));
+}
+
+export function PreflightIndicator({
+  status,
+  effectivePpi,
+  readyPpi,
+  minimumPpi,
+  issues = [],
+  actions = [],
+  onAction,
+  compact = false,
+  title = 'Print quality',
+  className,
+  style,
+}: PreflightIndicatorProps) {
+  const state = STATUS_COPY[status];
+  const quality = qualityPercent(effectivePpi, readyPpi);
+  const uniqueActions = [...new Set(actions)];
+
+  return (
+    <section
+      className={className}
+      data-agentsam-preflight=""
+      data-preflight-status={status}
+      data-preflight-tone={state.tone}
+      style={{
+        border: '1px solid var(--agentsam-preflight-border, rgba(90, 92, 98, 0.24))',
+        borderRadius: 12,
+        padding: compact ? 10 : 14,
+        background: 'var(--agentsam-preflight-bg, rgba(255,255,255,0.72))',
+        display: 'grid',
+        gap: compact ? 8 : 10,
+        ...style,
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'baseline',
+          justifyContent: 'space-between',
+          gap: 12,
+        }}
+      >
+        <strong style={{ fontSize: compact ? 12 : 13, fontWeight: 650 }}>{title}</strong>
+        <span
+          data-preflight-state=""
+          style={{
+            fontSize: 11,
+            opacity: 0.72,
+            textAlign: 'right',
+          }}
+        >
+          {state.label}
+        </span>
+      </div>
+
+      {quality != null ? (
+        <div style={{ display: 'grid', gap: 5 }}>
+          <div
+            aria-label={`Effective print resolution ${Math.round(effectivePpi!)} PPI`}
+            role="meter"
+            aria-valuemin={0}
+            aria-valuemax={readyPpi || 300}
+            aria-valuenow={Math.round(effectivePpi!)}
+            style={{
+              height: 5,
+              borderRadius: 999,
+              overflow: 'hidden',
+              background: 'var(--agentsam-preflight-track, rgba(90,92,98,0.14))',
+            }}
+          >
+            <div
+              style={{
+                height: '100%',
+                width: `${quality}%`,
+                borderRadius: 'inherit',
+                background:
+                  status === 'needs_variant' || status === 'unsupported'
+                    ? 'var(--agentsam-preflight-error, #9f4d4d)'
+                    : status === 'ready_with_warning'
+                      ? 'var(--agentsam-preflight-warning, #a87320)'
+                      : 'var(--agentsam-preflight-ready, #54745b)',
+                transition: 'width 120ms ease',
+              }}
+            />
+          </div>
+          <div
+            style={{
+              display: 'flex',
+              gap: 10,
+              fontSize: 11,
+              opacity: 0.72,
+            }}
+          >
+            <span>{Math.round(effectivePpi!)} PPI effective</span>
+            {readyPpi ? <span>{Math.round(readyPpi)} target</span> : null}
+            {minimumPpi && minimumPpi !== readyPpi ? (
+              <span>{Math.round(minimumPpi)} minimum</span>
+            ) : null}
+          </div>
+        </div>
+      ) : null}
+
+      {!compact && issues.length ? (
+        <div style={{ display: 'grid', gap: 4 }}>
+          {issues.slice(0, 3).map((issue) => (
+            <div key={issue.code} style={{ fontSize: 12, lineHeight: 1.35, opacity: 0.82 }}>
+              {issue.message}
+            </div>
+          ))}
+        </div>
+      ) : null}
+
+      {uniqueActions.length && onAction ? (
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 6 }}>
+          {uniqueActions.slice(0, compact ? 2 : 4).map((action) => (
+            <button
+              key={action}
+              type="button"
+              onClick={() => onAction(action)}
+              style={{
+                border: '1px solid var(--agentsam-preflight-button-border, rgba(70,72,76,0.24))',
+                borderRadius: 8,
+                padding: compact ? '5px 8px' : '6px 9px',
+                background: 'var(--agentsam-preflight-button-bg, rgba(255,255,255,0.82))',
+                color: 'inherit',
+                font: 'inherit',
+                fontSize: 11,
+                cursor: 'pointer',
+              }}
+            >
+              {labelForAction(action)}
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/packages/agentsam-workbench/src/manufacturing/index.ts

@@ -0,0 +1,2 @@
+export * from './PreflightIndicator';
+export * from './loading';

package/packages/agentsam-workbench/src/manufacturing/loading.ts

@@ -0,0 +1,147 @@
+import type {
+  LoadingSceneController,
+  LoadingSceneSemantic,
+  MetricPointProgress,
+} from '@inneranimalmedia/agentsam-loading-scene';
+
+export type ManufacturingLoadingState =
+  | 'UPLOADING'
+  | 'PREFLIGHT_CHECK'
+  | 'NORMALIZING_COLOR'
+  | 'VECTORIZING'
+  | 'COMPILING_MANUFACTURING'
+  | 'DIGITIZATION_HANDOFF';
+
+export type ReceiptLoadingState =
+  | 'VERIFYING_HASHES'
+  | 'PERSISTING_RECEIPT'
+  | 'CLEANING_WORKSPACE';
+
+interface PipelineStateConfig {
+  semantic: LoadingSceneSemantic;
+  label: string;
+  detail: string;
+}
+
+const MANUFACTURING_STATES: Record<ManufacturingLoadingState, PipelineStateConfig> = {
+  UPLOADING: {
+    semantic: 'asset_ingest',
+    label: 'Ingesting master artwork',
+    detail: 'Raster/vector parser',
+  },
+  PREFLIGHT_CHECK: {
+    semantic: 'preflight',
+    label: 'Evaluating physical print resolution',
+    detail: 'Calculating effective PPI from placement geometry',
+  },
+  NORMALIZING_COLOR: {
+    semantic: 'color_normalization',
+    label: 'Normalizing production color',
+    detail: 'Color profile and transparency normalization',
+  },
+  VECTORIZING: {
+    semantic: 'vectorization',
+    label: 'Tracing production paths',
+    detail: 'Raster boundary to monochrome vector',
+  },
+  COMPILING_MANUFACTURING: {
+    semantic: 'manufacturing_compile',
+    label: 'Compiling manufacturing derivative',
+    detail: 'Provider profile validation and export',
+  },
+  DIGITIZATION_HANDOFF: {
+    semantic: 'digitization_handoff',
+    label: 'Preparing digitization handoff',
+    detail: 'Embroidery source is prepared, not yet a stitch file',
+  },
+};
+
+const RECEIPT_STATES: Record<ReceiptLoadingState, PipelineStateConfig> = {
+  VERIFYING_HASHES: {
+    semantic: 'verification',
+    label: 'Verifying snapshot integrity',
+    detail: 'Pre/post hashes and stale-write evidence',
+  },
+  PERSISTING_RECEIPT: {
+    semantic: 'receipt_persistence',
+    label: 'Persisting receipt envelope',
+    detail: 'agentsam.receipt.v1 to durable catalog storage',
+  },
+  CLEANING_WORKSPACE: {
+    semantic: 'workspace_cleanup',
+    label: 'Cleaning ephemeral workspace',
+    detail: 'Reclaiming local temporary storage',
+  },
+};
+
+export interface PipelineTransitionOptions {
+  label?: string;
+  detail?: string;
+  progress?: number | null;
+  metricPoints?: MetricPointProgress;
+}
+
+function createController<TState extends string>(
+  controller: LoadingSceneController,
+  states: Record<TState, PipelineStateConfig>,
+  operationId: string,
+) {
+  let started = false;
+  let completed = false;
+
+  function transitionTo(state: TState, options: PipelineTransitionOptions = {}) {
+    const config = states[state];
+    if (!config || completed) return;
+
+    const payload = {
+      operationId,
+      semantic: config.semantic,
+      label: options.label || config.label,
+      detail: options.detail || config.detail,
+      progress: options.progress,
+      metricPoints: options.metricPoints,
+    };
+
+    if (!started) {
+      controller.start({ ...payload, scope: 'asset' });
+      started = true;
+      return;
+    }
+
+    controller.activity(payload);
+  }
+
+  return {
+    transitionTo,
+    complete() {
+      if (!started || completed) return;
+      completed = true;
+      controller.complete(operationId);
+    },
+    fail(detail?: string) {
+      if (!started || completed) return;
+      completed = true;
+      controller.fail(operationId, detail);
+    },
+    destroy() {
+      if (started && !completed) controller.complete(operationId);
+      completed = true;
+    },
+  };
+}
+
+export function createManufacturingLoadingController(
+  controller: LoadingSceneController,
+  { operationId = 'manufacturing-preflight' }: { operationId?: string } = {},
+) {
+  return createController(controller, MANUFACTURING_STATES, operationId);
+}
+
+export function createReceiptPipelineLoadingController(
+  controller: LoadingSceneController,
+  { operationId = 'receipt-pipeline' }: { operationId?: string } = {},
+) {
+  return createController(controller, RECEIPT_STATES, operationId);
+}
+
+export { MANUFACTURING_STATES, RECEIPT_STATES };

package/packages/agentsam-workbench/src/widgets/BuiltinWidget.tsx

@@ -0,0 +1,22 @@
+import { CountdownWidget } from './CountdownWidget';
+
+export interface BuiltinWidgetProps {
+  widgetId: string;
+  compact?: boolean;
+  configuration?: Record<string, unknown>;
+}
+
+export function BuiltinWidget({
+  widgetId,
+  compact = false,
+  configuration = {},
+}: BuiltinWidgetProps) {
+  if (widgetId === 'countdown') {
+    const requested = Number(configuration.durationMs);
+    const durationMs = Number.isFinite(requested) && requested > 0
+      ? requested
+      : 5 * 60_000;
+    return <CountdownWidget durationMs={durationMs} compact={compact} />;
+  }
+  return null;
+}

package/packages/agentsam-workbench/src/widgets/CountdownWidget.tsx

@@ -0,0 +1,68 @@
+import type { CSSProperties } from 'react';
+import { formatCountdown } from './countdown';
+import { useCountdown } from './useCountdown';
+
+export interface CountdownWidgetProps {
+  durationMs: number;
+  label?: string;
+  autoStart?: boolean;
+  compact?: boolean;
+  onComplete?: () => void;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function CountdownWidget({
+  durationMs,
+  label = 'Time remaining',
+  autoStart = false,
+  compact = false,
+  onComplete,
+  className,
+  style,
+}: CountdownWidgetProps) {
+  const countdown = useCountdown({ durationMs, autoStart, onComplete });
+  const primaryLabel =
+    countdown.phase === 'running'
+      ? 'Pause'
+      : countdown.phase === 'paused'
+        ? 'Resume'
+        : countdown.phase === 'complete'
+          ? 'Start again'
+          : 'Start';
+
+  const onPrimary = () => {
+    if (countdown.phase === 'running') countdown.pause();
+    else if (countdown.phase === 'paused') countdown.resume();
+    else countdown.start();
+  };
+
+  return (
+    <div
+      className={['agentsam-countdown', className].filter(Boolean).join(' ')}
+      data-countdown-phase={countdown.phase}
+      data-compact={compact ? 'true' : 'false'}
+      style={style}
+    >
+      <div
+        className="agentsam-countdown__time"
+        role="timer"
+        aria-label={label}
+        aria-live="off"
+      >
+        {formatCountdown(countdown.remainingMs)}
+      </div>
+      <div className="agentsam-countdown__controls">
+        <button type="button" className="agentsam-widget-button agentsam-widget-button--primary" onClick={onPrimary}>
+          {primaryLabel}
+        </button>
+        <button type="button" className="agentsam-widget-button" onClick={() => countdown.reset()}>
+          Reset
+        </button>
+      </div>
+      <span className="agentsam-countdown__status" role="status" aria-live="polite">
+        {countdown.phase === 'complete' ? 'Timer complete.' : ''}
+      </span>
+    </div>
+  );
+}

package/packages/agentsam-workbench/src/widgets/WidgetFrame.tsx

@@ -0,0 +1,56 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { AgentSamWidgetSize, AgentSamWidgetState } from '@inneranimalmedia/agentsam-contracts/widgets';
+
+export interface WidgetFrameProps {
+  title: ReactNode;
+  description?: ReactNode;
+  size?: AgentSamWidgetSize;
+  state?: AgentSamWidgetState;
+  actions?: ReactNode;
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+function stateLabel(state: AgentSamWidgetState | undefined): string | null {
+  if (!state || state.status === 'ready') return null;
+  if (state.status === 'empty') return 'No data';
+  if (state.status === 'stale') return 'Stale';
+  return 'Unavailable';
+}
+
+export function WidgetFrame({
+  title,
+  description,
+  size = 'small',
+  state,
+  actions,
+  children,
+  className,
+  style,
+}: WidgetFrameProps) {
+  const label = stateLabel(state);
+  const errorMessage = state && (state.status === 'stale' || state.status === 'error')
+    ? state.error.message
+    : null;
+
+  return (
+    <section
+      className={['agentsam-widget', className].filter(Boolean).join(' ')}
+      data-widget-size={size}
+      data-widget-state={state?.status ?? 'ready'}
+      style={style}
+    >
+      <header className="agentsam-widget__header">
+        <div className="agentsam-widget__heading">
+          <h2 className="agentsam-widget__title">{title}</h2>
+          {description ? <p className="agentsam-widget__description">{description}</p> : null}
+        </div>
+        {label ? <span className="agentsam-widget__state">{label}</span> : null}
+      </header>
+      <div className="agentsam-widget__body">{children}</div>
+      {errorMessage ? <p className="agentsam-widget__message" role="status">{errorMessage}</p> : null}
+      {actions ? <footer className="agentsam-widget__actions">{actions}</footer> : null}
+    </section>
+  );
+}

package/packages/agentsam-workbench/src/widgets/countdown.ts

@@ -0,0 +1,25 @@
+export type CountdownPhase = 'idle' | 'running' | 'paused' | 'complete';
+
+export function normalizeCountdownDuration(durationMs: number): number {
+  if (!Number.isFinite(durationMs)) return 0;
+  return Math.max(0, Math.round(durationMs));
+}
+
+export function remainingFromDeadline(deadlineMs: number, nowMs = Date.now()): number {
+  return Math.max(0, Math.round(deadlineMs - nowMs));
+}
+
+export function formatCountdown(remainingMs: number): string {
+  const totalSeconds = Math.max(0, Math.ceil(remainingMs / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (hours > 0) {
+    return [hours, minutes, seconds]
+      .map((part, index) => (index === 0 ? String(part) : String(part).padStart(2, '0')))
+      .join(':');
+  }
+
+  return `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
+}

package/packages/agentsam-workbench/src/widgets/index.ts

@@ -0,0 +1,6 @@
+export * from './countdown';
+export * from './useCountdown';
+export * from './WidgetFrame';
+export * from './CountdownWidget';
+export * from './registry';
+export * from './BuiltinWidget';

package/packages/agentsam-workbench/src/widgets/registry.ts

@@ -0,0 +1,13 @@
+import type { AgentSamWidgetDefinition } from '@inneranimalmedia/agentsam-contracts/widgets';
+
+export const BUILTIN_WIDGET_DEFINITIONS = Object.freeze([
+  Object.freeze({
+    id: 'countdown',
+    kind: 'countdown',
+    title: 'Countdown',
+    description: 'Compact deadline-based timer for focus blocks, launch windows, and task checkpoints.',
+    icon: 'clock-3',
+    sizes: ['small', 'medium'] as const,
+    deeplink: '/widgets',
+  } satisfies AgentSamWidgetDefinition),
+] satisfies readonly AgentSamWidgetDefinition[]);

package/packages/agentsam-workbench/src/widgets/useCountdown.ts

@@ -0,0 +1,128 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  normalizeCountdownDuration,
+  remainingFromDeadline,
+  type CountdownPhase,
+} from './countdown';
+
+export interface UseCountdownOptions {
+  durationMs: number;
+  autoStart?: boolean;
+  tickMs?: number;
+  onComplete?: () => void;
+}
+
+export interface CountdownController {
+  phase: CountdownPhase;
+  durationMs: number;
+  remainingMs: number;
+  deadlineMs: number | null;
+  start: () => void;
+  pause: () => void;
+  resume: () => void;
+  reset: (durationMs?: number) => void;
+}
+
+export function useCountdown({
+  durationMs: durationInput,
+  autoStart = false,
+  tickMs = 250,
+  onComplete,
+}: UseCountdownOptions): CountdownController {
+  const normalizedInput = normalizeCountdownDuration(durationInput);
+  const [durationMs, setDurationMs] = useState(normalizedInput);
+  const [remainingMs, setRemainingMs] = useState(normalizedInput);
+  const [deadlineMs, setDeadlineMs] = useState<number | null>(null);
+  const [phase, setPhase] = useState<CountdownPhase>(autoStart && normalizedInput > 0 ? 'running' : 'idle');
+  const onCompleteRef = useRef(onComplete);
+  const completionReportedRef = useRef(false);
+
+  useEffect(() => {
+    onCompleteRef.current = onComplete;
+  }, [onComplete]);
+
+  useEffect(() => {
+    setDurationMs(normalizedInput);
+    if (phase === 'idle') setRemainingMs(normalizedInput);
+    // A completed countdown stays at 00:00 until the user starts or resets it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [normalizedInput]);
+
+  const begin = useCallback((baseRemainingMs: number) => {
+    const nextRemaining = normalizeCountdownDuration(baseRemainingMs);
+    if (nextRemaining <= 0) {
+      setRemainingMs(0);
+      setDeadlineMs(null);
+      setPhase('complete');
+      return;
+    }
+
+    completionReportedRef.current = false;
+    setRemainingMs(nextRemaining);
+    setDeadlineMs(Date.now() + nextRemaining);
+    setPhase('running');
+  }, []);
+
+  const start = useCallback(() => {
+    begin(phase === 'complete' || remainingMs <= 0 ? durationMs : remainingMs);
+  }, [begin, durationMs, phase, remainingMs]);
+
+  const pause = useCallback(() => {
+    if (phase !== 'running' || deadlineMs === null) return;
+    const nextRemaining = remainingFromDeadline(deadlineMs);
+    setRemainingMs(nextRemaining);
+    setDeadlineMs(null);
+    setPhase(nextRemaining <= 0 ? 'complete' : 'paused');
+  }, [deadlineMs, phase]);
+
+  const resume = useCallback(() => {
+    if (phase !== 'paused') return;
+    begin(remainingMs);
+  }, [begin, phase, remainingMs]);
+
+  const reset = useCallback((nextDurationMs = normalizedInput) => {
+    const nextDuration = normalizeCountdownDuration(nextDurationMs);
+    completionReportedRef.current = false;
+    setDurationMs(nextDuration);
+    setRemainingMs(nextDuration);
+    setDeadlineMs(null);
+    setPhase('idle');
+  }, [normalizedInput]);
+
+  useEffect(() => {
+    if (!autoStart || normalizedInput <= 0) return;
+    if (phase === 'running' && deadlineMs === null) begin(normalizedInput);
+  }, [autoStart, begin, deadlineMs, normalizedInput, phase]);
+
+  useEffect(() => {
+    if (phase !== 'running' || deadlineMs === null) return;
+
+    const tick = () => {
+      const nextRemaining = remainingFromDeadline(deadlineMs);
+      setRemainingMs(nextRemaining);
+      if (nextRemaining > 0) return;
+
+      setDeadlineMs(null);
+      setPhase('complete');
+      if (!completionReportedRef.current) {
+        completionReportedRef.current = true;
+        onCompleteRef.current?.();
+      }
+    };
+
+    tick();
+    const interval = setInterval(tick, Math.max(50, tickMs));
+    return () => clearInterval(interval);
+  }, [deadlineMs, phase, tickMs]);
+
+  return {
+    phase,
+    durationMs,
+    remainingMs,
+    deadlineMs,
+    start,
+    pause,
+    resume,
+    reset,
+  };
+}