Spatial

// Monorepo / workspace today — npm publish TBD
pnpm add @syncframe/core @syncframe/redis

interface SpatialMeta {
  worldBbox: { width: number; height: number };  // default 1920×1080
  renderMode: 'calibration' | 'content';
  contentLayerId?: string;  // consumer sets via SpatialServer.initialMeta (not a lib default)
  screens: Record<string, ScreenEntry>;
  identifyTrigger?: { screenName: string; at: number } | null; // often merged at SSE build
}

interface ScreenEntry {
  pose: ScreenPose;
  createdAt: string;
  sessions: Record<string, ScreenSession>;
}

interface ScreenPose {
  worldX: number;
  worldY: number;
  worldWidth: number;
  worldHeight: number;
}

import { SyncServer } from '@syncframe/core/server';
import { RedisStore, RedisTransport } from '@syncframe/redis';
import { SpatialServer, ensureScreen } from '@syncframe/spatial/server';

const sync = new SyncServer({
  store: new RedisStore({ redis }),
  transport: new RedisTransport({ redis, createSubscriber }),
  namespace: 'dot-demo',
});

const spatial = new SpatialServer({ sync });

await spatial.ensureInitialized();
await spatial.apply((m) => ensureScreen(m, 'wall-left'));
await spatial.publish();

// Pure reducers (testable, framework-agnostic)
import {
  ensureScreen,
  updatePose,
  deleteScreen,
  heartbeat,
  setRenderMode,
  setWorldBbox,
  setContentLayerId,
  pruneStaleSessions,
  parseSpatialMeta,
} from '@syncframe/spatial/server';

// spatial.apply((m) => updatePose(m, name, pose) ?? m)
// spatial.apply((m) => heartbeat(m, name, session) ?? m)

import { worldToScreen, screenToWorld } from '@syncframe/spatial/server';

const pose = { worldX: 100, worldY: 200, worldWidth: 400, worldHeight: 300 };

// World (300, 350) → normalized (0.5, 0.5) — center of this pose's bbox
worldToScreen({ x: 300, y: 350 }, pose);

// Pixel placement (consumer — map normalized or world units to clientWidth/Height):
const scaleX = viewportWidth / pose.worldWidth;
const screenX = (worldX - pose.worldX) * scaleX;

// Operator — registry + render mode, no heartbeat
import { useSpatialSnapshot, listScreenNames, isScreenOnline } from '@syncframe/spatial/react';

const { spatial, snapshot, connected } = useSpatialSnapshot({
  streamEndpoint: '/api/dot/stream',
});

// Display — registry + pose + heartbeat + identify
import { useDisplaySurface } from '@syncframe/spatial/react';

const { pose, isCalibration, isContent, deleted, identifyTrigger } = useDisplaySurface({
  screenName: 'wall-left',
  streamEndpoint: '/api/dot/stream',
  apiBase: '/api/dot',
  heartbeat: true,
});

// Content motion — separate core anchor channel
import { useAnchor } from '@syncframe/core/react';

const dotAnchor = useAnchor('dot', '/api/dot/stream');

// Display detects deletion from snapshot absence OR heartbeat 404
// useSelfScreen stops heartbeating when deleted

type WorldShapePaint =
  | { kind: 'solid'; color: string }
  | { kind: 'image'; url: string };

interface WorldShape {
  x: number; y: number; width: number; height: number;
  paint: WorldShapePaint;
  label?: string; opacity?: number;
}

interface SpatialContentLayer {
  id: string;
  label: string;
  evaluateFrame: (ctx: WorldEvalContext) => WorldFrame;
  MapView: ComponentType<WorldPreviewContext>;
  Display: ComponentType<ContentLayerDisplayProps>;
}

// @syncframe/spatial/ui — projection only, no draw opinions
import { projectWorldFrameToViewport } from '@syncframe/spatial/ui';

import { ChromeFreeDisplay, TopDownRoomMap } from '@syncframe/spatial/ui';
import { dotLayer } from '@/lib/dot-layer';

// Operator map — consumer MapView; screen overlays on top
<TopDownRoomMap
  spatial={spatial}
  snapshot={snapshot}
  clock={clock}
  MapView={dotLayer.MapView}
  selectedScreenName={selected}
/>

// display/layout.tsx — hide site header/footer
<div data-presentation className="fixed inset-0 bg-black">…</div>

// Thin page glue: register screenName, then one spatial component
<ChromeFreeDisplay
  screenName="left"
  streamEndpoint="/api/dot/stream"
  apiBase="/api/dot"
  clockEndpoint="/api/clock"
  contentLayer={dotLayer}
  presentation
/>

// Demo: Redis key syncframe:{namespace}:spatial:identify (EX 5s)
// Merged in buildDotDemoSnapshot() — not persisted in meta JSON

// Bundled in ChromeFreeDisplay; also importable from @syncframe/spatial/ui
<IdentifyFlash trigger={identifyTrigger} screenName={screenName} />

// dot-layer.tsx — data + consumer renderers
export const dotLayer: SpatialContentLayer = {
  id: 'dot',
  evaluateFrame: evaluateDotFrame,
  MapView: DotMapView,      // lib/dot-render.tsx — solid + image paint
  Display: DotDisplay,      // DotViewport + offset decay
};

// Motion math (no React): apps/site/lib/dot.ts

// ring-layer.tsx — twelve petals from one evaluateFrame
export const ringLayer: SpatialContentLayer = {
  id: 'ring',
  evaluateFrame: evaluateRingFrame,
  MapView: RingMapView,     // lib/ring-render.tsx
  Display: RingViewport,
};

// Operator: POST /api/ring/spin { action: 'start' | 'pause' }
// Displays: /demo/ring/display?screenName=nw

{
  "anchors": {
    "dot": {
      "at": 1730000000000,
      "value": { "x": 120, "y": 80 },
      "motion": { "kind": "linear2dBouncing" }
    }
  },
  "meta": {
    "spatial": {
      "worldBbox": {
        "width": 1920,
        "height": 1080
      },
      "renderMode": "content",
      "contentLayerId": "dot",
      "screens": {
        "wall-left": {
          "pose": {
            "worldX": 0,
            "worldY": 0,
            "worldWidth": 960,
            "worldHeight": 1080
          },
          "createdAt": "2026-06-07T12:00:00.000Z",
          "sessions": {
            "abc123": {
              "sessionId": "abc123",
              "clientWidthPx": 1920,
              "clientHeightPx": 1080,
              "devicePixelRatio": 2,
              "lastSeenAt": "2026-06-07T12:00:10.000Z"
            }
          }
        }
      },
      "identifyTrigger": null
    }
  },
  "contentData": null
}