@cueframe/kernel 0.0.1 → 0.1.1

package/dist/_members/authoring/transpileComponent.d.ts

@@ -11,7 +11,7 @@
  * remotion / animate as endowments — and (b) assign `exports.default = <Component>`.
  *
  * This is the Node/native-esbuild sibling of the desktop `transpileJsx`
- * (cueframe/src/llm/transpile.ts, esbuild-wasm) and the director's
+ * (apps/studio/src/llm/transpile.ts, esbuild-wasm) and the director's
  * `serverTranspiler` (activities/director.ts). All three share ONE transpile
  * config — the SSOT `ESBUILD_JSX_OPTIONS` + `postProcessForSandbox` in
  * ./transpileHelper — so a live component transpiled here is byte-identical to

package/dist/_members/cloud-import/CloudImportService.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Singleton Uppy service for imports (local + cloud).
+ *
+ * Uses @uppy/aws-s3 for multipart uploads directly to R2 via the
+ * upload-signing CF Worker. Replaces the old TUS-based upload path.
+ *
+ * Owns the Uppy instance lifecycle (headless — no Dashboard plugin).
+ * React integration is handled by ImportProvider (single mount at app root).
+ * MediaItem pre-creation is handled by MediaItemPreprocessor (Uppy plugin).
+ */
+import Uppy from '@uppy/core';
+import { MediaItemPreprocessor } from './MediaItemPreprocessor.js';
+interface CloudImportConfig {
+    uploadSigningUrl: string;
+}
+export interface CloudUploadResult {
+    uploadURL: string;
+    fileName: string;
+    fileSize: number;
+}
+declare class CloudImportService {
+    private uppy;
+    private config;
+    /** Lazy-init: create Uppy + plugins on first use. */
+    init(config: CloudImportConfig): Uppy;
+    /** Get the Uppy instance (must call init() first). */
+    getUppy(): Uppy;
+    /** Get the MediaItemPreprocessor plugin. */
+    getPreprocessor(): MediaItemPreprocessor;
+    /** Update upload metadata (uploadToken, userId, projectId). */
+    setMeta(meta: Record<string, string>): void;
+}
+/** Module-level singleton. */
+export declare const cloudImportService: CloudImportService;
+export {};

package/dist/_members/cloud-import/ImportProvider.d.ts

@@ -0,0 +1,73 @@
+/**
+ * ImportProvider — single mount at app root.
+ *
+ * Initializes the CloudImportService, wires auth callbacks, and provides
+ * the useImport() hook to child components. Wraps children in Uppy's
+ * UppyContextProvider so headless hooks (useDropzone, useUppyState, etc.)
+ * work anywhere in the tree.
+ *
+ * The import dialog UI is injected via `dialogSlot` to avoid circular
+ * dependency between @cueframe/cloud-import and @cueframe/pro.
+ */
+import { type ReactNode } from 'react';
+import type Uppy from '@uppy/core';
+import type { CloudUploadResult } from './CloudImportService.js';
+interface ImportContextValue {
+    openModal: () => void;
+    closeModal: () => void;
+    isOpen: boolean;
+    uppy: Uppy;
+    /**
+     * Can this lane actually take an upload right now?
+     *
+     * A cloud import needs an identity: `getUploadMeta` mints an org-scoped
+     * upload token, so with none the modal opens onto a request that can only
+     * fail. This is DATA because the provider is now a fixture of the tree — it
+     * mounts for the life of the desktop process, signed in or not, so its
+     * PRESENCE stopped being the answer to this question (it was, back when the
+     * whole cloud stack mounted only inside a confirmed auth handshake).
+     */
+    available: boolean;
+}
+export interface ImportProviderProps {
+    children: ReactNode;
+    /** Whether this lane can take an upload — see `ImportContextValue.available`.
+     *  Required, with no default: the one thing a caller must not forget is the
+     *  fact that decides whether a control is offered at all. */
+    available: boolean;
+    /** React element to render the import dialog (e.g. <ImportDialog />) */
+    dialogSlot?: ReactNode;
+    uploadSigningUrl: string;
+    /** Called before opening the modal — returns upload metadata (token, userId, etc). */
+    getUploadMeta?: () => Promise<Record<string, string>>;
+    /** Pre-create a mediaItem — called by the preprocessor plugin before upload starts. */
+    createMediaItem?: (file: {
+        name: string;
+        size: number;
+        mimeType: string;
+    }) => Promise<string>;
+    onUploadComplete?: (results: CloudUploadResult[]) => void;
+    onError?: (error: Error) => void;
+}
+export declare function ImportProvider({ children, available, dialogSlot, uploadSigningUrl, getUploadMeta, createMediaItem, onUploadComplete, onError, }: ImportProviderProps): import("react").JSX.Element;
+/** Hook to access the import modal and Uppy instance. Must be used inside <ImportProvider>. */
+export declare function useImport(): ImportContextValue;
+/**
+ * The context WHEN THE LANE CAN BE USED, and `null` otherwise — for surfaces
+ * that offer the cloud modal only where it works and fall back where it does
+ * not (the pro ImportButton, which drops to the local file picker).
+ *
+ * It used to answer presence alone, and presence used to be the same fact:
+ * the provider mounted only inside a confirmed auth handshake. It mounts for
+ * the life of the desktop process now (Task 11 — a provider that appears and
+ * disappears re-parents the app), so presence would offer a cloud modal to a
+ * signed-out user whose upload-token request can only fail: a control that
+ * looks alive and silently does nothing.
+ *
+ * Still ONE fact, read from the tree rather than mirrored: the alternative —
+ * a caller re-deriving `isDesktop && cloudEnabled && signedIn` — is the drift
+ * class that crashed the desktop ("useImport must be used within
+ * <ImportProvider>") whenever the two copies disagreed.
+ */
+export declare function useImportIfAvailable(): ImportContextValue | null;
+export {};

package/dist/_members/cloud-import/MediaItemPreprocessor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Uppy preprocessor plugin that pre-creates a mediaItem in the backend
+ * before the upload starts. This guarantees convexMediaItemId is in the
+ * upload metadata before the first byte goes out — no race condition.
+ *
+ * The actual creation function is injected via setCreateFn() so the plugin
+ * stays decoupled from Convex/auth concerns.
+ */
+import { BasePlugin } from '@uppy/core';
+import type { Uppy, Meta } from '@uppy/core';
+type CreateMediaItemFn = (file: {
+    name: string;
+    size: number;
+    mimeType: string;
+}) => Promise<string>;
+export declare class MediaItemPreprocessor extends BasePlugin<Record<string, never>, Meta, Record<string, never>> {
+    static pluginId: string;
+    private createFn;
+    private preprocessBound;
+    constructor(uppy: Uppy, opts?: Record<string, never>);
+    /** Inject the creation function (called from ImportProvider). */
+    setCreateFn(fn: CreateMediaItemFn | null): void;
+    install(): void;
+    uninstall(): void;
+    private preprocess;
+}
+export {};

package/dist/_members/cloud-import/cloudConfig.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Single source of truth for cloud endpoint resolution.
+ *
+ * One input (convexUrl) → deterministic output (all cloud endpoints).
+ * No fallback chains, no env var reading, no defaults.
+ */
+export type CloudEnvironment = 'dev' | 'staging' | 'production';
+export interface CloudEndpoints {
+    convexUrl: string;
+    uploadSigningUrl: string;
+}
+export declare const ENVIRONMENTS: Record<CloudEnvironment, CloudEndpoints>;
+/** Detect environment from a Convex deployment URL.
+ *
+ * Convex exposes two domains per deployment: queries (`data*`) and HTTP
+ * actions (`api*`). Callers pass either form depending on which client
+ * they own, so detection has to recognize both:
+ *   prod    → api.cueframe.ai     | data.cueframe.ai
+ *   staging → api-dev.cueframe.ai | data-dev.cueframe.ai
+ */
+export declare function detectEnvironment(convexUrl?: string): CloudEnvironment;
+/** Resolve all cloud endpoints from a Convex URL. */
+export declare function getEndpoints(convexUrl: string): CloudEndpoints;

package/dist/_members/cloud-import/index.d.ts

@@ -0,0 +1,9 @@
+export { ImportProvider, useImport, useImportIfAvailable } from './ImportProvider.js';
+export type { ImportProviderProps } from './ImportProvider.js';
+export { cloudImportService } from './CloudImportService.js';
+export type { CloudUploadResult } from './CloudImportService.js';
+export { ENVIRONMENTS, detectEnvironment, getEndpoints } from './cloudConfig.js';
+export type { CloudEnvironment, CloudEndpoints } from './cloudConfig.js';
+export { multipartUpload } from './multipartUpload.js';
+export type { MultipartUploadOptions, MultipartUploadResult } from './multipartUpload.js';
+export { useDropzone, useUppyState, useUppyEvent, } from '@uppy/react';

package/dist/_members/cloud-import/multipartUpload.d.ts

@@ -0,0 +1,12 @@
+export interface MultipartUploadOptions {
+    file: File;
+    signingUrl: string;
+    token: string;
+    metadata?: Record<string, string>;
+    onProgress?: (fraction: number) => void;
+}
+export interface MultipartUploadResult {
+    location: string;
+    mediaItemId: string;
+}
+export declare function multipartUpload(opts: MultipartUploadOptions): Promise<MultipartUploadResult>;

package/dist/_members/composition/ops/compositionOps.d.ts

@@ -4,7 +4,7 @@
  * All operations are side-effect-free: no persistence, no logging. Only
  * state mutations via set/get on the wire-shape Composition.
  *
- * Mirrors the desktop store's v2 ops (cueframe/src/store/compositionStore/
+ * Mirrors the desktop store's v2 ops (apps/studio/src/store/compositionStore/
  * compositionOps.ts). The OSS module drops desktop-only concerns
  * (corrections, transcriptDoc) — those live on the desktop envelope.
  */
@@ -89,6 +89,7 @@ export declare function createCompositionOps(get: OpsGet, set: OpsSet): {
     setCropIntents: (clipId: string, segments: ReframeSegment[] | null) => void;
     setEffects: (clipId: string, effects: PerClipEffect[]) => void;
     setCaptionStyle: (style: CaptionStyle) => void;
+    setCaptionDepth: (zPlane: "front" | "behind-subject") => void;
     setCaptions: (segments: CaptionSegment[], style?: CaptionStyle, derivedFrom?: {
         clipId: string;
     }) => void;

package/dist/_members/composition/ops/types.d.ts

@@ -2,7 +2,7 @@
  * Composition types — v2 wire-shape.
  *
  * The OSS shared composition module mirrors the desktop store's v2
- * shape (cueframe/src/store/compositionStore/types.ts) minus desktop-only
+ * shape (apps/studio/src/store/compositionStore/types.ts) minus desktop-only
  * envelope concerns (corrections, transcriptDoc, isLoaded).
  *
  * Used by:

package/dist/_members/composition/projection/behind-readiness.d.ts

@@ -0,0 +1,127 @@
+/**
+ * CAN THIS OVERLAY ACTUALLY GO BEHIND THE SUBJECT — answered in the editor,
+ * before a render is paid for.
+ *
+ * The render already decides this, in the director's `resolveBehindPlacement`:
+ * a behind-subject overlay whose clip has no matte, no geometry sidecar, or too
+ * little subject presence is DEGRADED — `zPlane` flipped back to `front` and the
+ * authored `anchor` deleted — and the reason is recorded in a `degraded[]` array
+ * that both of its callers discard. So the user flips the toggle, pays for a
+ * render, and finds out from the output.
+ *
+ * This module answers the same question from data the editor already has on the
+ * media row, so the toggle can tell the truth at the moment it is flipped.
+ *
+ * ── IT IS ONLY WORTH ANYTHING IF IT AGREES WITH THE SERVER ──────────────────
+ * Every rule below mirrors a specific server rule, named at its call site. Two
+ * helpers are currently duplicated from the private `@cueframe/shared/
+ * variant-keys` (`hashMatteIntent`, `clipOverlapsBehindWindow`); they live here
+ * because this package is the shared one, and the private copies become
+ * re-exports of these when the fact-record work lands. Until then the agreement
+ * is held by `__tests__/behind-readiness.test.ts`, whose key fixture is a hash
+ * taken from PRODUCTION rather than invented.
+ *
+ * ── WHAT IT CANNOT ANSWER ───────────────────────────────────────────────────
+ * The server has a FOURTH degrade path — the occlusion budget — which needs the
+ * `.geometry.json` sidecar from R2, and the client has no presigned URL for it.
+ * So `subject-present` means "the preconditions hold", NOT "this is guaranteed
+ * to render behind", and UI copy must not promise more.
+ */
+/** A matte intent: the clip's SOURCE window plus what is being cut out.
+ *  Mirrors `MatteIntentLike` in the private variant-keys. */
+export interface MatteIntentLike {
+    startSec: number;
+    endSec: number;
+    subjectClass: "person" | "product";
+}
+/** The fields this module reads off a `mediaItems.mattes[hash]` entry — the
+ *  same two `resolveBehindPlacement` reads out of its `matteGeometry` map. */
+export interface MatteEntryLike {
+    geometryR2Key?: string;
+    presenceFraction?: number;
+}
+/** The clip an overlay will be placed against, and the source window whose
+ *  matte answers for it. */
+export interface BehindTarget {
+    mediaId: string;
+    window: {
+        startSec: number;
+        endSec: number;
+    };
+}
+/**
+ * Why a behind-subject overlay will or will not survive the render. The three
+ * failing states correspond 1:1 to the server's degrade reasons: `no-clip` and
+ * `no-subject` both degrade as `"no-subject"` there, `no-matte` as
+ * `"no-geometry"`.
+ */
+export type BehindReadiness = {
+    state: "no-clip";
+} | {
+    state: "no-matte";
+    target: BehindTarget;
+} | {
+    state: "no-subject";
+    target: BehindTarget;
+    presenceFraction: number;
+} | {
+    state: "subject-present";
+    target: BehindTarget;
+};
+/**
+ * Content-address a matte intent, byte-identically to the server's
+ * `hashMatteIntent`. Milliseconds-rounded so float jitter cannot miss a cached
+ * matte; 12 hex chars. Async because `crypto.subtle` is — available in the
+ * webview and in Node alike.
+ *
+ * The bake VERSION is deliberately not hashed (it segments the R2 key instead),
+ * so this key is stable across model bumps.
+ */
+export declare function matteIntentKey(intent: MatteIntentLike): Promise<string>;
+/**
+ * The clip a behind-subject overlay anchors against: **the first media clip on
+ * a VIDEO track, in track→content order, whose timeline range overlaps the
+ * overlay**. This is `resolveBehindPlacement`'s rule, and it is deliberately
+ * NOT `computeMatteWindowsByMediaId`'s — that one also scans audio and image
+ * tracks, because it answers a different question (which mattes to bake).
+ * Mirroring the wrong one of the two would put the editor and the render into
+ * exactly the disagreement this module exists to remove.
+ *
+ * The returned `window` is the clip's SOURCE trim, defaulted the way
+ * `renders.ts` defaults it: `trim.start ?? 0`, `trim.end ?? start + duration`.
+ * That is the window the matte is keyed by.
+ *
+ * Returns null when the overlay is unknown, or floats over no video clip —
+ * which the server degrades as `"no-subject"`.
+ */
+export declare function primaryClipForOverlay(composition: unknown, overlayId: string): BehindTarget | null;
+export interface BehindReadinessInput {
+    /** The wire-shape composition currently open in the editor. */
+    composition: unknown;
+    /** The overlay being inspected. It need NOT already be behind-subject — the
+     *  editor asks this to decide what to show BEFORE the toggle is flipped. */
+    overlayId: string;
+    /** `mediaItems.mattes`, per media id, exactly as it arrives from Convex. */
+    mattesByMediaId: Record<string, Record<string, MatteEntryLike> | undefined>;
+}
+/**
+ * Will this overlay actually render behind the subject? Mirrors the first three
+ * of `resolveBehindPlacement`'s four gates, in the same order:
+ *
+ *   1. no primary clip                  → server: degrade("no-subject")
+ *   2. no matte / no geometry sidecar   → server: degrade("no-geometry")
+ *   3. presence below the floor         → server: degrade("no-subject")
+ *
+ * The fourth (occlusion budget) is not knowable client-side — see the header.
+ */
+export declare function behindReadinessForOverlay(input: BehindReadinessInput): Promise<BehindReadiness>;
+/**
+ * The same verdict from an ALREADY-RESOLVED target — the half that actually
+ * costs something (a SHA-256) split from the half that is a pure walk.
+ *
+ * The editor calls this one. `primaryClipForOverlay` is sync, so a component
+ * can memoize the target on the composition and then depend only on the
+ * window's two numbers plus the media's matte record — instead of re-hashing on
+ * every keystroke that produces a new composition reference.
+ */
+export declare function behindReadinessForTarget(target: BehindTarget | null, mattes: Record<string, MatteEntryLike> | undefined): Promise<BehindReadiness>;

package/dist/_members/composition/projection/index.d.ts

@@ -3,5 +3,7 @@ export * from "./cardTokens.js";
 export * from "./composition-floor.js";
 export * from "./safe-zones.js";
 export * from "./behind-placement.js";
+export * from "./behind-readiness.js";
+export * from "./reframe-readiness.js";
 export * from "./occlusion-budget.js";
 export * from "./cropProjection.js";

package/dist/_members/composition/projection/reframe-readiness.d.ts

@@ -0,0 +1,156 @@
+/**
+ * WHICH CLIPS WANT A CROP, AND DO WE HAVE WHAT IT TAKES — answered in the
+ * editor, from data the media row already carries.
+ *
+ * The sibling of `behind-readiness.ts`, one rung down the fidelity ladder. That
+ * module asks whether a SILHOUETTE exists so an overlay can go behind a person;
+ * this one asks whether a BOX TRACK exists so a clip can follow one. Same shape,
+ * same discipline, ~40× apart in what the answer costs.
+ *
+ * ── WHY IT EXISTS ───────────────────────────────────────────────────────────
+ * A follow-the-speaker reframe is authored in the editor and only takes effect
+ * at render, because the crop trajectory is derived from a SUBJECT TRACK the
+ * editor never asked for. So the editor showed an uncropped source while the
+ * render produced a moving crop — the "editor shows something the render will
+ * not honour" defect, in its second location. Deriving the trajectory locally
+ * fixes that, and the derive needs to find the right track first. That lookup
+ * is what this module is.
+ *
+ * ── IT IS ONLY WORTH ANYTHING IF IT AGREES WITH THE SERVER ──────────────────
+ * `reframeTargets` mirrors `collectTrajectoryDeriveJobs` (private
+ * `renders.ts`) — the walk the SHIP render uses to decide which clips derive a
+ * trajectory and at which window. `sourceWindowKey` mirrors `hashSourceWindow`
+ * (private `@cueframe/shared/variant-keys`) byte for byte; the golden fixtures
+ * in `__tests__/reframe-readiness.test.ts` are hashes taken from PRODUCTION
+ * rather than invented, for the same reason `behind-readiness`'s are.
+ *
+ * ── WHAT IT DELIBERATELY DOES NOT CHECK ─────────────────────────────────────
+ * The DETECTOR VERSION. The server skips a track whose `detectorVersion` is not
+ * the current `DETECTOR_VERSION`, and the app cannot ask that without a third,
+ * unguarded mirror of a string whose TS↔Python sync is already CI-guarded on
+ * both existing copies. So the editor derives off whatever track sits at the
+ * window. A version bump means the render re-detects and the framing shifts
+ * slightly — same subject, same authored intent, and far closer to the truth
+ * than showing an uncropped source. A decision, not an omission.
+ */
+/** A source window. Subject tracks key on this — the window, plus the producer
+ *  when it is not the default face detector. Mirrors `SourceWindowLike`. */
+export interface SourceWindowLike {
+    startSec: number;
+    endSec: number;
+    /**
+     * Which producer detected the track: 'face' (YuNet/SCRFD, the default) or
+     * 'person' (YOLO11x + BoT-SORT). Folded into the hash ONLY when it is not
+     * 'face', so existing face-track keys never churn and a person track for the
+     * same window gets a DISTINCT key instead of overwriting the face one.
+     */
+    detector?: "face" | "person";
+}
+/** The fields this module reads off a `mediaItems.subjectTracks[hash]` entry. */
+export interface SubjectTrackEntryLike {
+    /** R2 object key — the STABLE identity every server-side reader matches on. */
+    trackR2Key?: string;
+    /**
+     * Presigned URL for that key, added ALONGSIDE it by `resolveR2Urls`. The row
+     * carries only a SUMMARY of the track (the face roster, a count); the
+     * per-frame boxes `deriveTrajectory` needs are the R2 object, so this is the
+     * one field that makes a client-side derive possible at all.
+     */
+    trackUrl?: string;
+    detectorVersion?: string;
+    window?: {
+        startSec: number;
+        endSec: number;
+    };
+    /** The inline face roster — who is in this window, for a per-person picker. */
+    faces?: Array<{
+        faceId: string;
+        bbox: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        speakingShare?: number;
+    }>;
+}
+/**
+ * Content-address a source window, byte-identically to the server's
+ * `hashSourceWindow`. Milliseconds-rounded so float jitter cannot miss a cached
+ * track; 12 hex chars. Async because `crypto.subtle` is — available in the
+ * webview and in Node alike.
+ *
+ * The detector is omitted from the canonical form when it is 'face', which is
+ * NOT a shortcut: it is what keeps every already-cached face-track key valid.
+ */
+export declare function sourceWindowKey(window: SourceWindowLike): Promise<string>;
+/** A clip that has authored a reframe, and the window whose track answers for
+ *  it. `segments` travels along because `deriveTrajectory` takes it verbatim. */
+export interface ReframeTarget {
+    clipId: string;
+    mediaId: string;
+    window: {
+        startSec: number;
+        endSec: number;
+    };
+    /** The authored `source.reframe.segments`, untouched — the derive owns their
+     *  shape, and re-typing it here would be a fourth place to keep in sync. */
+    segments: unknown[];
+}
+/**
+ * Does this reframe track a real subject? A geometric one (a screen-recording
+ * point-zoom, an honest center crop) needs nothing detected and must NEVER be
+ * handed a detection bill — nor be told it is waiting for one.
+ */
+export declare function reframeNeedsDetection(segments: unknown[]): boolean;
+/**
+ * Every clip in the composition that has authored a reframe, with the source
+ * window its track is keyed by.
+ *
+ * MIRRORS `collectTrajectoryDeriveJobs`, including the two rules that are easy
+ * to get subtly wrong:
+ *   · only VIDEO and IMAGE tracks (an audio clip is `kind:"media"` too, and a
+ *     viewport crop is meaningless for sound)
+ *   · the window is the SOURCE TRIM, defaulted exactly as `renders.ts` defaults
+ *     it — `trim.start ?? 0`, `trim.end ?? start + clip.duration`
+ *
+ * Walked defensively with no zod, the `collectBehindWindows` convention, so it
+ * is safe in every bundle.
+ */
+export declare function reframeTargets(composition: unknown): ReframeTarget[];
+/**
+ * What the editor can say about one reframed clip.
+ *
+ * `geometric` is a distinct state and not a convenience: a point-zoom on a
+ * screen recording is fully derivable with no detection, so calling it
+ * "waiting for a track" would be a lie that also implies a charge.
+ */
+export type ReframeReadiness = 
+/** No detection needed — derives off a faceless stub, today, for free. */
+{
+    state: "geometric";
+}
+/** The track exists and can be fetched. */
+ | {
+    state: "track-ready";
+    entry: SubjectTrackEntryLike;
+    trackUrl: string;
+}
+/** A track is registered but carries no presigned URL, so the client cannot
+ *  derive. The RENDER still can — it reads the key directly. */
+ | {
+    state: "track-unfetchable";
+    entry: SubjectTrackEntryLike;
+}
+/** Nothing detected at this window yet. This is the state that buys one. */
+ | {
+    state: "no-track";
+};
+/**
+ * Can the editor derive this clip's crop trajectory right now?
+ *
+ * `subjectTracks` is `mediaItems.subjectTracks` for the target's media, exactly
+ * as it arrives from Convex — undefined for an item with no cloud perception,
+ * which is the honest shape for a local-only import.
+ */
+export declare function reframeReadinessForTarget(target: ReframeTarget, subjectTracks: Record<string, SubjectTrackEntryLike> | undefined): Promise<ReframeReadiness>;

package/dist/_members/composition/timeline/placement.d.ts

@@ -1,7 +1,7 @@
 /**
  * WHERE A SOURCE GOES.
  *
- * Hoisted from `cueframe/src/components/Timeline/fabric/placement.ts` (2026-08-23)
+ * Hoisted from `apps/studio/src/components/Timeline/fabric/placement.ts` (2026-08-23)
  * for the reason the module's own header predicted and the repo rule requires:
  * the cloud director writes compositions too, so a placement rule that lives in
  * the desktop is a rule the cloud does not have. This is now the single home.