@pictor-sdk/ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,833 @@
+import * as _pictor_sdk_core from '@pictor-sdk/core';
+import { Size, Layer, TextSpan, TextLayerData, EditorProfile, EditorPlugin, EditorDocument, ExportSpec, InsertableImage, ToolPanelProps, Dispatch, InsertImageOptions, InsertImageTransaction, Rect, EditorStore, LayerSnapState, Transform, Stroke } from '@pictor-sdk/core';
+export { POST_PROFILE, STORY_PROFILE } from '@pictor-sdk/core';
+import * as React from 'react';
+import React__default, { ReactNode, ComponentType } from 'react';
+import { PreviewLayerTransform } from '@pictor-sdk/skia';
+
+/**
+ * One sticker offered by the panel.
+ *
+ * Supplied by the host: the library ships no sticker artwork, so what appears
+ * here is entirely the app's own.
+ */
+interface StickerAsset {
+    id: string;
+    /** image source (require() result, {uri}, or URL string) */
+    source: unknown;
+    intrinsic?: Size;
+    label?: string;
+}
+/**
+ * Sticker tab. Sticker catalogs are host-supplied — pass them via
+ * <Editor stickers={…}> (or replace this panel through a plugin tool Panel).
+ * DECISION: no sticker assets ship with the library (same reasoning as LUTs).
+ */
+declare function StickerPanel(): React__default.JSX.Element;
+
+/**
+ * Theming is one token object on context — no style props on individual
+ * components (ARCHITECTURE.md). Override any subset via <Editor theme={…}>.
+ */
+interface EditorTheme {
+    colors: {
+        background: string;
+        surface: string;
+        text: string;
+        textMuted: string;
+        accent: string;
+        danger: string;
+        track: string;
+        thumb: string;
+    };
+    radii: {
+        sm: number;
+        md: number;
+        lg: number;
+    };
+    spacing: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+    };
+    font: {
+        size: number;
+        sizeSm: number;
+        weight: '400' | '500' | '600' | '700';
+    };
+}
+/** The bundled dark theme. Every value is overridable; see {@link mergeTheme}. */
+declare const defaultTheme: EditorTheme;
+/** A theme override — any subset of any group, the rest falling back to the default. */
+type PartialTheme = {
+    [K in keyof EditorTheme]?: Partial<EditorTheme[K]>;
+};
+/** Apply an override onto the default theme, one group at a time. */
+declare function mergeTheme(overrides?: PartialTheme): EditorTheme;
+/** Carries the resolved theme. `<Editor>` provides it; components read it with {@link useTheme}. */
+declare const ThemeContext: React.Context<EditorTheme>;
+/** The theme in effect. Defaults outside an `<Editor>` rather than throwing. */
+declare function useTheme(): EditorTheme;
+
+interface ComposerInsets {
+    /** Distance from the bottom of the screen to place the control bar. */
+    bottom: number;
+    /** True while the keyboard occupies screen space. */
+    keyboardVisible: boolean;
+    /** Animation duration to match the platform's own, clamped to something sane. */
+    duration: number;
+}
+
+/**
+ * The state and commands behind a text-editing session.
+ *
+ * This is the whole contract a composer needs, so the default composer and any
+ * replacement are built on exactly the same surface — which is what makes the
+ * default one genuinely replaceable rather than merely swappable-in-principle.
+ *
+ * The session owns its history batch. The text tool has no bottom-sheet panel —
+ * the composer *is* its UI — so `ToolPanelHost` never opens one for it, and the
+ * session must, or every keystroke would be its own undo entry. Opening it here
+ * also fixes the ordering: the batch is open before the draft is created,
+ * which it would not be if a parent opened it in its own mount effect (effects
+ * run child-first).
+ *
+ * @experimental
+ */
+interface TextSessionController {
+    /** The layer being edited — a fresh draft, or the one that was selected. */
+    layer: Layer | undefined;
+    /** Whether this session created the layer, which decides blank-Done. */
+    kind: 'draft' | 'existing';
+    /** Current text. Mirrors the document; drives the input's value. */
+    value: string;
+    /** Replace the text. */
+    setValue(next: string): void;
+    /** The span the composer styles as a whole. */
+    span: TextSpan | undefined;
+    /** Full layer data, for alignment/fill/stroke/shadow controls. */
+    data: TextLayerData | undefined;
+    /** Patch the styled span — font, size, colour, weight, spacing. */
+    styleSpan(patch: Partial<TextSpan>): void;
+    /** Patch layer-level text data — alignment, fill, stroke, shadow, maxWidth. */
+    styleText(patch: Partial<TextLayerData>): void;
+    /** Set a normalized font size, held inside the supported range. */
+    setSize(size: number): void;
+    /**
+     * Finish. A draft that ended blank is discarded and records nothing.
+     *
+     * Returns the committed layer id, or `null` when nothing was kept.
+     */
+    commit(): string | null;
+    /** Abandon. Restores the document to exactly its state when the tool opened. */
+    cancel(): void;
+}
+/** Hooks into the composing session — chiefly what to do when it ends. */
+interface UseTextSessionOptions {
+    /**
+     * Edit this layer instead of resolving from the selection. Lets a custom UI
+     * request editing for a specific layer — the re-entry API.
+     */
+    layerId?: string;
+    /** Called once the session has committed or been discarded. */
+    onFinished?: (layerId: string | null) => void;
+}
+/**
+ * Open a text-editing session for the current selection (or `layerId`).
+ *
+ * Creates its draft on mount so the canvas shows the layer immediately and the
+ * caret has something to sit on.
+ */
+declare function useTextSession(options?: UseTextSessionOptions): TextSessionController;
+
+/**
+ * Props a text composer receives.
+ *
+ * The default composer is built on exactly this, so a replacement has
+ * everything the built-in one had — no privileged access to reach for.
+ *
+ * @experimental
+ */
+interface TextComposerProps {
+    /** The live session: layer, value, style commands, Done and Cancel. */
+    session: TextSessionController;
+    /** Where the controls should sit, given the keyboard. */
+    insets: ComposerInsets;
+    /** Finish and keep the text. */
+    onDone(): void;
+    /** Abandon, restoring the document. */
+    onCancel(): void;
+}
+/**
+ * The full-screen Story text composer.
+ *
+ * An absolute overlay above the canvas. The canvas keeps rendering the layer
+ * being typed — there is no second text renderer and no editing chrome inside
+ * `renderDocument` — so what is on screen while composing is what exports.
+ *
+ * The `TextInput` itself is invisible and stretched over the canvas: it owns
+ * the caret, the platform selection handles and the IME, while the *visible*
+ * text is the real Skia layer underneath. That is what keeps preview and export
+ * identical without giving up native text editing.
+ *
+ * @experimental
+ */
+declare function TextComposer({ session, insets, onDone, onCancel }: TextComposerProps): React__default.JSX.Element;
+/**
+ * Mounts a text session and the composer for it, and keeps the keyboard inset
+ * up to date. This is what `<Editor>` renders while the text tool is active.
+ *
+ * @experimental
+ */
+declare function TextComposerHost({ Composer, }: {
+    /** Replace the default composer without replacing the canvas or editor. */
+    Composer?: React__default.ComponentType<TextComposerProps>;
+}): React__default.JSX.Element;
+
+/** What the top bar slot receives: the transaction actions and undo state. */
+interface TopBarProps {
+    onCancel?: () => void;
+    onNext?: () => void;
+    /** true while an export is running (Next shows a spinner). */
+    busy?: boolean;
+}
+/** The default top bar: cancel, undo/redo, and the action that ends the session. */
+declare function TopBar({ onCancel, onNext, busy }: TopBarProps): React__default.JSX.Element;
+
+/**
+ * Every region of the default editor is a slot: pass your own component to
+ * replace it, or null to remove it. All slots are built exclusively on the
+ * public headless hooks — replacing one can never break the others.
+ */
+interface EditorSlots {
+    TopBar: ComponentType<TopBarProps> | null;
+    CanvasStage: ComponentType<CanvasStageProps> | null;
+    ToolRail: ComponentType | null;
+    ToolPanelHost: ComponentType | null;
+    /**
+     * The full-screen text composer, shown while the `text` tool is active.
+     *
+     * Replace it to ship your own composition UI without replacing the canvas or
+     * the editor; it receives everything the default one gets. `null` removes it,
+     * leaving text editing to a host-built surface.
+     *
+     * @experimental
+     */
+    TextComposer: ComponentType<TextComposerProps> | null;
+}
+/** What the canvas slot receives. Children draw over the canvas, in its coordinates. */
+interface CanvasStageProps {
+    children?: ReactNode;
+    /** Reported when a layer's image source fails to load. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * The canvas plus whichever gesture surface the active tool calls for.
+ *
+ * Exactly one surface is mounted at a time — precedence lives in
+ * `resolveGestureSurface`, not in this JSX — so two recognisers can never
+ * arbitrate over the same touch.
+ */
+declare function CanvasStage({ children, onError }: CanvasStageProps): React__default.JSX.Element;
+/**
+ * What `<Editor>` accepts: a profile, its plugins, a document or a source, and
+ * any slots or theme you want to replace.
+ */
+interface EditorProps {
+    profile: EditorProfile;
+    plugins?: EditorPlugin[];
+    /** Image source for a fresh document (or pass initialDocument). */
+    source?: unknown;
+    intrinsic?: Size;
+    initialDocument?: EditorDocument;
+    onExport?: (bytes: Uint8Array) => void | Promise<void>;
+    onCancel?: () => void;
+    onError?: (error: unknown) => void;
+    exportSpec?: Partial<ExportSpec>;
+    slots?: Partial<EditorSlots>;
+    theme?: PartialTheme;
+    /** Host-supplied sticker catalog for the built-in sticker panel. */
+    stickers?: StickerAsset[];
+    /**
+     * Asked to supply photos when the user presses the add-photo control.
+     *
+     * The library never touches the gallery: permissions, the picker and any
+     * HEIC/HEIF transcoding stay with the host, which is what keeps it free of
+     * Expo and of native code. Resolve `null` or `[]` for cancellation, which
+     * adds nothing. Omit it and the control renders unavailable rather than
+     * throwing.
+     *
+     * @experimental
+     */
+    requestImages?: () => Promise<readonly InsertableImage[] | null>;
+}
+/** Merge slot overrides over the defaults. Pure — unit tested. */
+declare function mergeSlots(overrides?: Partial<EditorSlots>): EditorSlots;
+/**
+ * The batteries-included editor. `<Editor profile={POST_PROFILE} … />` gives
+ * the full IG-style flow; every part is replaceable via `slots`.
+ */
+declare function Editor({ profile, plugins, source, intrinsic, initialDocument, onExport, onCancel, onError, exportSpec, slots, theme, stickers, requestImages, }: EditorProps): React__default.JSX.Element;
+
+/** The toolbar IS profile.tools — rendered from the registry, never hardcoded. */
+declare function ToolRail(): React__default.JSX.Element;
+
+/**
+ * Built-in panels for the built-in tool ids. Pure — unit tested.
+ *
+ * `text` deliberately has no panel: the text tool is served by the full-screen
+ * composer slot, which owns its own controls. Leaving a panel here would open a
+ * second history batch alongside the composer's and render a bottom sheet
+ * underneath it.
+ */
+declare function resolvePanel(toolId: string | null, pluginPanel: unknown, builtins?: Record<string, ComponentType>): ComponentType<Partial<ToolPanelProps>> | null;
+/** Renders the active tool's panel — plugin-provided Panel wins over built-ins. */
+declare function ToolPanelHost(): React__default.JSX.Element | null;
+
+/**
+ * The base photo — the bottom-most image layer.
+ *
+ * Unchanged, and deliberately still available: some capabilities are genuinely
+ * about *the base photo* rather than about whichever photo is selected — Story
+ * media placement and the derived background are computed from it. Panels that
+ * edit "the current image" use {@link useTargetImageLayer} instead.
+ */
+declare function useBaseImageLayer(): _pictor_sdk_core.Layer | undefined;
+/**
+ * The LUT filter strip: live thumbnails, tap to apply, second tap on the
+ * active filter reveals the intensity slider.
+ */
+declare function FilterStrip(): React__default.JSX.Element | null;
+
+/**
+ * The image an open panel edits, **pinned for the whole session**.
+ *
+ * Resolved once, from the selection at the moment the panel mounts, and then
+ * held by id. `ToolPanelHost` mounts a fresh panel per tool activation, so a
+ * mount *is* a session, and closing and reopening resolves again.
+ *
+ * The pinning is the point. Re-resolving each render would let a selection
+ * change mid-drag redirect the next slider movement to a different photo — an
+ * edit landing silently on the wrong image, which is worse than an edit that
+ * does nothing. So when the target is deleted, locked or hidden mid-session
+ * this returns `null` and the panel disables its controls; it never quietly
+ * falls back to the base.
+ *
+ * `useBaseImageLayer` is unchanged and still means *the base photo*. Use it
+ * where a capability is genuinely base-only — Story media layout, the derived
+ * background — rather than by inertia.
+ *
+ * @experimental
+ */
+declare function useTargetImageLayer(): Layer | null;
+
+/**
+ * The add-photo control: one press, one picker, one undo entry.
+ *
+ * Nothing happens on mount. Opening a picker because a panel appeared would
+ * take the choice away from the user and make a stray tool tap launch the
+ * gallery, so acquisition waits for an explicit press.
+ *
+ * All the asynchronous behaviour lives in `createAddPhotoController`, which is
+ * testable without mounting anything. This is the shell.
+ *
+ * @experimental
+ */
+declare function AddPhotoPanel(): React__default.JSX.Element;
+
+/**
+ * Acquiring photos from the host, then inserting them.
+ *
+ * Deliberately **not** a React component. Acquisition is asynchronous and has
+ * to survive a re-render, refuse a second request while one is in flight, and
+ * do nothing at all if the panel is gone by the time the host answers — none of
+ * which is expressible as render logic, and all of which is worth testing
+ * without mounting anything.
+ *
+ * Acquisition is also kept separate from insertion so a host that wants neither
+ * this controller nor the default panel can call `createImageLayers` and
+ * `insertImageCommands` directly.
+ *
+ * @experimental
+ */
+interface AddPhotoControllerOptions {
+    /**
+     * Supplied by the host. Resolving `null` or `[]` means the user cancelled,
+     * which must add nothing — no command, no selection change, no history entry.
+     */
+    requestImages?: () => Promise<readonly InsertableImage[] | null>;
+    dispatch: Dispatch;
+    select: (ids: string[]) => void;
+    /** Anything the host's picker throws, or a result that is not usable. */
+    onError?: (error: unknown) => void;
+    /** Presentation and transaction options forwarded to the core helpers. */
+    insert?: InsertImageOptions & InsertImageTransaction;
+}
+/**
+ * A live add-photo session.
+ *
+ * @experimental
+ */
+interface AddPhotoController {
+    /** Ask the host for photos and insert whatever comes back. */
+    request: () => Promise<void>;
+    /** True while a request is in flight; a second press is ignored. */
+    isPending: () => boolean;
+    /**
+     * Whether the host supplied a way to ask at all.
+     *
+     * **Session-scoped.** Captured when the controller is created, which for the
+     * bundled panel means when it mounts. A host that adds `requestImages` while
+     * the panel is open sees it unavailable until the tool is reopened — the
+     * mount is the session boundary everywhere else in this panel too, and a
+     * control that becomes live mid-session is a stranger surprise than one that
+     * waits for the next open.
+     */
+    isAvailable: () => boolean;
+    /** Called when the panel unmounts: a late result is then discarded. */
+    dispose: () => void;
+}
+/**
+ * The host resolved with something that is not a list of insertable images.
+ *
+ * Reported rather than coerced: guessing at a malformed result would insert
+ * layers the host did not mean to add.
+ *
+ * @experimental
+ */
+declare class InvalidImageResultError extends Error {
+    constructor();
+}
+/**
+ * Wire a host's picker to the core insertion helpers.
+ *
+ * Acquisition stays separate from insertion, so a host that wants neither this
+ * controller nor the default panel can call `createImageLayers` and
+ * `insertImageCommands` itself.
+ *
+ * @experimental
+ */
+declare function createAddPhotoController({ requestImages, dispatch, select, onError, insert, }: AddPhotoControllerOptions): AddPhotoController;
+
+/**
+ * Callbacks the host supplies to `<Editor>` that panels deep in the tree need.
+ *
+ * Held in a **ref** rather than state. A callback prop is usually an inline
+ * arrow recreated every render, so storing it in state would notify on every
+ * render and re-render forever; consumers read `.current` at call time instead
+ * and never re-render because the host re-created its closure.
+ *
+ * @experimental
+ */
+interface HostCallbacks {
+    /**
+     * Asked to supply photos when the user presses the add-photo control.
+     *
+     * The library never touches the gallery itself: permissions, the picker and
+     * any HEIC/HEIF transcoding are the host's, which is what keeps the library
+     * free of Expo and of native code. Resolve `null` or `[]` for cancellation.
+     */
+    requestImages?: () => Promise<readonly InsertableImage[] | null>;
+    /** Where a failed request is reported. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Makes the host's callbacks reachable from panels deep in the tree.
+ *
+ * Mounted by `<Editor>`; a host composing its own editor from slots mounts it
+ * itself, or omits it and the controls render unavailable.
+ *
+ * @experimental
+ */
+declare function HostCallbacksProvider({ value, children, }: {
+    value: HostCallbacks;
+    children?: React__default.ReactNode;
+}): React__default.JSX.Element;
+/**
+ * The host's callbacks, as a stable ref.
+ *
+ * Returns an empty set outside an `<Editor>` rather than throwing — a panel
+ * rendered standalone should degrade to "unavailable", not crash.
+ *
+ * @experimental
+ */
+declare function useHostCallbacks(): {
+    current: HostCallbacks;
+};
+
+/**
+ * The Adjust tab: the 13 tools from profile/registry order, one centred
+ * slider with a detent at 0 (a 0 adjustment is a provable render no-op).
+ */
+declare function AdjustPanel(): React__default.JSX.Element | null;
+
+/** Crop tool: aspect presets from the profile, 90° rotate, straighten dial. */
+declare function CropPanel(): React__default.JSX.Element | null;
+
+/**
+ * Pure crop math for the Crop tool (unit-tested in Node).
+ *
+ * Aspect selection: the document canvas takes the chosen aspect (constant
+ * width) and the image layer gets a maximal centred crop matching it.
+ */
+declare function canvasSizeForAspect(current: Size, aspect: number | 'free'): Size;
+/** Maximal centred crop (normalized within the source) with the given aspect. */
+declare function centeredCropForAspect(intrinsic: Size, aspect: number): Rect;
+/** The straighten dial's range: ±45°, in radians. */
+declare const STRAIGHTEN_LIMIT: number;
+/** Straighten dial value (-1..1) ↔ radians (±45°). */
+declare function straightenToRadians(value: number): number;
+/** Radians to dial value (-1..1), clamped to the limit. */
+declare function radiansToStraighten(rad: number): number;
+
+/**
+ * A slider's value and range.
+ *
+ * `centered` is the adjustment shape — `-1..1` resting in the middle with a
+ * detent at zero. A quantity with no meaningful negative (Lux, tint strength,
+ * blur) uses `min: 0` and `centered: false` instead, which is the control shape
+ * measured on the reference editor.
+ */
+interface SliderProps {
+    /** -1..1 when centered, 0..1 otherwise */
+    value: number;
+    min?: number;
+    max?: number;
+    /** show a centre detent and snap to 0 within ±0.05 (adjustment sliders) */
+    centered?: boolean;
+    onStart?: () => void;
+    onChange: (value: number) => void;
+    onEnd?: () => void;
+    testID?: string;
+    /** Floating value label shown above the thumb. */
+    valueLabel?: string;
+    /**
+     * Inert and dimmed. For a control whose value has nothing meaningful to
+     * write yet — dragging it would record something untrue.
+     */
+    disabled?: boolean;
+}
+/** Dependency-free horizontal slider with an optional centre detent. */
+declare function Slider({ value, min, max, centered, onStart, onChange, onEnd, testID, valueLabel, disabled, }: SliderProps): React__default.JSX.Element;
+
+/** The straighten dial: a value in -1..1 and the callbacks bracketing a drag. */
+interface StraightenRulerProps {
+    value: number;
+    min?: number;
+    max?: number;
+    onStart?: () => void;
+    onChange(value: number): void;
+    onEnd?: () => void;
+}
+/** Fine, zero-snapping ruler for angle correction. Values are degrees. */
+declare function StraightenRuler({ value, min, max, onStart, onChange, onEnd }: StraightenRulerProps): React__default.JSX.Element;
+
+/** The fitted canvas's size in dp, for turning touches into document units. */
+interface GestureMetrics {
+    /** canvas size in dp (the fitted preview) */
+    width: number;
+    height: number;
+}
+/** Emitted the moment a gesture snaps — the hook for haptics. */
+interface GestureSnapEvent {
+    kind: 'rotation' | 'centerX' | 'centerY';
+}
+/**
+ * Host callbacks a gesture controller may fire.
+ *
+ * Callbacks rather than behaviour: haptics would mean a native dependency, so
+ * the library reports the moment and the host decides what it means.
+ */
+interface GestureControllerOptions {
+    /** e.g. trigger haptics — optional callback, no haptics dependency here. */
+    onSnap?: (event: GestureSnapEvent) => void;
+}
+/**
+ * Pure gesture → command translation, shared by the RN gesture wiring and
+ * unit tests. Pan/pinch/rotate report cumulative deltas; the controller
+ * recomputes the transform from the base captured at gesture start and
+ * commits through a history batch so the whole gesture is ONE undo step.
+ *
+ * DECISION: shared values give 60fps feedback on the UI thread; document
+ * commits hop to JS per frame (cheap — one reducer pass at preview scale)
+ * inside the batch. True UI-thread document mutation would need a worklet
+ * store and is out of scope for v0.1.
+ */
+declare function createGestureController(store: Pick<EditorStore, 'getState' | 'dispatch' | 'select' | 'registry'>, getMetrics: () => GestureMetrics | null, options?: GestureControllerOptions): {
+    /** Pan/pinch/rotate lifecycles — call begin/end once per recognizer. */
+    begin: () => void;
+    end: () => void;
+    setPan(xDp: number, yDp: number): void;
+    setPinch(scale: number): void;
+    setRotate(rad: number): void;
+    /** Tap in canvas dp → hit-test → select (empty tap clears selection). */
+    tap(xDp: number, yDp: number): void;
+    /** true while a gesture is in flight (used to mute other UI). */
+    isActive: () => boolean;
+};
+/** Turns raw gesture input into layer transforms, with snapping. */
+type GestureController = ReturnType<typeof createGestureController>;
+
+/** Overrides forwarded to whichever gesture surface the active tool mounts. */
+interface EditorGesturesProps {
+    /** Optional haptic hook — fired once per snap engagement. */
+    onSnap?: (event: GestureSnapEvent) => void;
+}
+/**
+ * Invisible gesture surface for <EditorCanvas children={…}/>: tap to select,
+ * pan/pinch/rotate the selected layer. Recognizers run simultaneously on the
+ * UI thread; commits are batched into a single undo step (see controller).
+ */
+declare function EditorGestures({ onSnap }: EditorGesturesProps): React__default.JSX.Element;
+
+/** Overrides for overlay-layer gestures, defaulting to the profile's settings. */
+interface LayerGestureSurfaceProps {
+    /** Fired once per snap engagement — hook up haptics here if you want them. */
+    onSnap?: (event: GestureSnapEvent) => void;
+}
+/**
+ * Direct manipulation of overlay layers: grab the top-most layer under the
+ * finger and pan, focal-pinch and rotate it on the UI thread.
+ *
+ * Three things make this feel right, and each is covered by tests:
+ *
+ * - **Focal composition.** Scale and rotation happen about the gesture
+ *   centroid, so the document point under the fingers stays under them.
+ * - **Pointer-count re-basing.** Gesture Handler restarts its cumulative
+ *   translation/scale/rotation when a finger lands or lifts. Every recognizer
+ *   value is read relative to an origin captured at the last re-base, and the
+ *   frame re-bases from the live transform whenever the pointer count changes
+ *   — so two fingers going to one does not jump.
+ * - **One history entry.** The document is written exactly once, when the
+ *   gesture settles, and not at all if nothing actually moved.
+ */
+declare function LayerGestureSurface({ onSnap }: LayerGestureSurfaceProps): React__default.JSX.Element;
+
+/** The centre and rotation guides shown while a layer snaps. */
+interface InteractionGuidesProps {
+    /** Label shown above the delete target. */
+    deleteLabel?: string;
+}
+/**
+ * Alignment guides and the drag-to-delete target.
+ *
+ * DECISION: these are plain React Native views layered over `<EditorCanvas>`,
+ * not Skia nodes inside `renderDocument`. Transient interaction chrome then
+ * has no way of reaching an export — stronger than an `isExport` check — and
+ * the single render path (invariant 1) stays untouched.
+ *
+ * Render as a child of `<EditorCanvas>`, which sizes its children to the
+ * fitted document box, so percentage offsets here are document-relative.
+ */
+declare function InteractionGuides({ deleteLabel }: InteractionGuidesProps): React__default.JSX.Element | null;
+
+/** Overrides for base-media gestures, defaulting to the profile's settings. */
+interface StoryMediaGestureSurfaceProps {
+    /** Fired when a media gesture starts and ends — for host haptics/chrome. */
+    onInteractionChange?: (active: boolean) => void;
+}
+/** Find the document's base media — the bottom-most layer, if it is an image. */
+declare function useBaseMediaLayer(): Layer | undefined;
+/**
+ * Direct manipulation of the Story base photo: one-finger reposition, focal
+ * pinch and rotation, held inside rotation-aware pan bounds with rubber-band
+ * resistance and a bounded settle.
+ *
+ * Mounted only while the `media` tool is active, so it cannot compete with
+ * overlay or drawing gestures. The transform is written to the document once
+ * per settled gesture; because the tool session already opened a history batch
+ * (see `ToolPanelHost`), a whole session of adjustments collapses into one undo
+ * entry, and a session that changed nothing records none.
+ */
+declare function StoryMediaGestureSurface({ onInteractionChange, }: StoryMediaGestureSurfaceProps): React__default.JSX.Element | null;
+
+/**
+ * Which gesture surface owns the canvas.
+ *
+ * Precedence is decided by the active tool and nothing else, so it is a pure
+ * function that can be tested without mounting anything — and so the rule is
+ * stated in one place rather than implied by JSX nesting.
+ */
+type GestureSurfaceKind = 'media' | 'draw' | 'crop' | 'tilt' | 'text' | 'overlay';
+/**
+ * Resolve the surface for the active tool.
+ *
+ * - `text` — the full-screen composer owns the screen, so **no** canvas surface
+ *   is mounted at all. Not mounting is the strongest form of "disabled": there
+ *   is no recogniser to arbitrate with, so a tap meant for the caret cannot
+ *   start a canvas gesture, and a drag begins immediately once composing ends.
+ * - `media` — the base photo tool owns the surface, so the photo moves and
+ *   overlays are inert.
+ * - `draw` — drawing owns the surface, so strokes are never interpreted as
+ *   layer drags.
+ * - `crop` — the Post crop surface.
+ * - `tilt` — placing the selective-focus region, which needs the whole canvas;
+ *   overlay hit-testing would steal the drag to whatever sits under the finger.
+ * - anything else (including no active tool) — overlay hit-testing, which
+ *   excludes the base photo, so dragging text or a sticker cannot move it.
+ */
+declare function resolveGestureSurface(activeTool: string | null | undefined): GestureSurfaceKind;
+
+/**
+ * The base-photo tool panel.
+ *
+ * It is deliberately thin: the gestures live on the canvas surface, and the
+ * Cancel/Done transaction comes from `ToolPanelHost`, which opens a history
+ * batch for any tool with a panel. The panel only offers the affordances that
+ * are not gestures — a reset to the initial fit — and explains the interaction.
+ */
+declare function MediaPanel(): React__default.JSX.Element;
+
+/** Overrides for crop gestures, defaulting to the profile's interaction settings. */
+interface CropGestureSurfaceProps {
+    /** Override profile crop fit for this surface. */
+    fit?: 'contain' | 'cover';
+    maxScale?: number;
+    /** Enable free two-finger rotation; disabled by the default Post profile. */
+    rotationEnabled?: boolean;
+    /** Optional host haptic/motion callback. */
+    onInteractionChange?: (active: boolean) => void;
+}
+/**
+ * Fixed-viewport photo crop gestures. Pan and focal-point pinch run as shared
+ * values on the UI thread; one normalized transform is committed on release.
+ */
+declare function CropGestureSurface({ fit, maxScale, rotationEnabled, onInteractionChange }: CropGestureSurfaceProps): React__default.JSX.Element | null;
+
+/** Rule-of-thirds overlay shown only while crop interaction is active. */
+declare function CropGrid({ always }: {
+    always?: boolean;
+}): React__default.JSX.Element | null;
+
+/**
+ * Transient interaction state shared between the gesture surfaces and the
+ * chrome. None of it is part of the document: it never reaches history,
+ * serialization or export.
+ *
+ * Per-frame transforms stay on the UI thread as shared values (`previews`).
+ * Only the discrete flags below cross to the JS thread, and only when they
+ * actually change — a drag starting, a guide engaging, the delete target being
+ * entered — so the render path is untouched while fingers move.
+ */
+interface InteractionState {
+    previews: readonly PreviewLayerTransform[];
+    setPreview(preview: PreviewLayerTransform | null): void;
+    cropActive: boolean;
+    setCropActive(active: boolean): void;
+    /** True while a layer is being dragged/scaled/rotated. */
+    layerDragActive: boolean;
+    setLayerDragActive(active: boolean): void;
+    /** True while the dragged layer is over the delete target. */
+    overDeleteTarget: boolean;
+    setOverDeleteTarget(over: boolean): void;
+    /** Which alignment guides are currently engaged. */
+    snap: LayerSnapState;
+    setSnap(snap: LayerSnapState): void;
+}
+/**
+ * Shares the in-flight interaction between the gesture surfaces and the canvas.
+ *
+ * How a live preview transform reaches the renderer without going through the
+ * document — which would mean dispatching every frame.
+ */
+declare function InteractionProvider({ children }: {
+    children?: React__default.ReactNode;
+}): React__default.JSX.Element;
+/** The current interaction. Throws outside an `<Editor>`, where there is none. */
+declare function useInteractionState(): InteractionState;
+
+/**
+ * Text tab: add a text layer, then edit the selected one — content, font,
+ * size, color, alignment, and the fill treatment (solid / per-line
+ * @experimental). Editing happens in the panel for v0.2; DECISION:
+ * on-canvas edit-in-place needs a native text-input overlay pass, deferred.
+ */
+declare function TextPanel(): React__default.JSX.Element;
+
+/** Draw tab: brush picker, color swatches + eyedropper, width slider. */
+declare function DrawPanel(): React__default.JSX.Element;
+
+/**
+ * Z-order UI: top-most first, tap to select, reorder and delete.
+ * (Drag-to-delete on canvas maps to the same layer/remove command.)
+ */
+declare function LayersPanel(): React__default.JSX.Element;
+
+/** Layout grids: snap the image layers into the chosen arrangement. */
+declare function LayoutPanel(): React__default.JSX.Element;
+
+/** The bundled multi-photo arrangements, by cell count and split direction. */
+type LayoutPreset = '1' | '2v' | '2h' | '3v' | '4grid';
+/** One slot in a layout: where its photo sits, in normalized document units. */
+interface LayoutCell {
+    /** centre + scale in normalized document units */
+    x: number;
+    y: number;
+    /** width of the cell as a fraction of document width */
+    scale: number;
+}
+/**
+ * Story layout grids: cell centres and scales for placing the first N image
+ * layers. Pure — unit tested. Cells are defined as document fractions so any
+ * canvas size works.
+ */
+declare function layoutCells(preset: LayoutPreset, _doc: Size): LayoutCell[];
+/** The transform patch that moves a layer into a cell, leaving its other fields alone. */
+declare function cellToTransformPatch(cell: LayoutCell): Partial<Transform>;
+
+/** The active brush: kind, colour and width. Width is a fraction of document width. */
+interface BrushConfig {
+    brush: Stroke['brush'];
+    color: string;
+    /** 0..1 of document width */
+    width: number;
+}
+/**
+ * Pure drawing controller: converts a pan gesture into a stroke on the
+ * top-most draw layer (created on first use), committed as ONE undo step.
+ * Live feedback comes from patching the stroke into the document on every
+ * move inside the history batch.
+ */
+declare function createDrawController(store: Pick<EditorStore, 'getState' | 'dispatch'>, getMetrics: () => GestureMetrics | null, getBrush: () => BrushConfig): {
+    begin(xDp: number, yDp: number): void;
+    move(xDp: number, yDp: number): void;
+    end(): void;
+    isDrawing: () => boolean;
+};
+/** Accumulates touch points into strokes and commits them to the document. */
+type DrawController = ReturnType<typeof createDrawController>;
+
+/** The brush a drawing session starts with. */
+declare const DEFAULT_BRUSH: BrushConfig;
+/**
+ * Freehand drawing capture, active while the draw tool is open. In
+ * eyedropper mode a tap samples the rendered pixel color into the brush.
+ */
+declare function DrawingSurface(): React__default.JSX.Element;
+
+/**
+ * A tiny shared key/value store for panel ↔ canvas coordination (brush
+ * config, sticker catalogs, eyedropper mode). Ephemeral — never touches the
+ * document or history.
+ */
+interface UiStateStore {
+    get<T>(key: string, fallback: T): T;
+    set(key: string, value: unknown): void;
+    subscribe(listener: () => void): () => void;
+}
+/** A scratch store for UI state that is neither document nor history. */
+declare function createUiStateStore(): UiStateStore;
+/**
+ * Holds ephemeral panel state — which tab is open, which swatch is selected.
+ *
+ * Deliberately outside the document: none of it should be serialized, undoable,
+ * or survive the editor closing.
+ */
+declare function UiStateProvider({ children }: {
+    children?: React__default.ReactNode;
+}): React__default.JSX.Element;
+/** Read and write one key of the ephemeral UI state. Throws outside an `<Editor>`. */
+declare function useUiState<T>(key: string, fallback: T): [T, (value: T) => void];
+
+export { type AddPhotoController, type AddPhotoControllerOptions, AddPhotoPanel, AdjustPanel, type BrushConfig, CanvasStage, type CanvasStageProps, CropGestureSurface, type CropGestureSurfaceProps, CropGrid, CropPanel, DEFAULT_BRUSH, type DrawController, DrawPanel, DrawingSurface, Editor, EditorGestures, type EditorGesturesProps, type EditorProps, type EditorSlots, type EditorTheme, FilterStrip, type GestureController, type GestureControllerOptions, type GestureMetrics, type GestureSnapEvent, type GestureSurfaceKind, type HostCallbacks, HostCallbacksProvider, InteractionGuides, type InteractionGuidesProps, InteractionProvider, InvalidImageResultError, LayerGestureSurface, type LayerGestureSurfaceProps, LayersPanel, type LayoutCell, LayoutPanel, type LayoutPreset, MediaPanel, type PartialTheme, STRAIGHTEN_LIMIT, Slider, type SliderProps, type StickerAsset, StickerPanel, StoryMediaGestureSurface, type StoryMediaGestureSurfaceProps, StraightenRuler, type StraightenRulerProps, TextComposer, TextComposerHost, type TextComposerProps, TextPanel, type TextSessionController, ThemeContext, ToolPanelHost, ToolRail, TopBar, type TopBarProps, UiStateProvider, type UiStateStore, type UseTextSessionOptions, canvasSizeForAspect, cellToTransformPatch, centeredCropForAspect, createAddPhotoController, createDrawController, createGestureController, createUiStateStore, defaultTheme, layoutCells, mergeSlots, mergeTheme, radiansToStraighten, resolveGestureSurface, resolvePanel, straightenToRadians, useBaseImageLayer, useBaseMediaLayer, useHostCallbacks, useInteractionState, useTargetImageLayer, useTextSession, useTheme, useUiState };