@flatkit/types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zwyk Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,501 @@
+type Point = {
+    x: number;
+    y: number;
+};
+/** A closed ring (the closing point is not duplicated). */
+type Polygon = Point[];
+/** Axis-aligned bounding box (alignment, snapping, marquee hit-test). */
+type BBox = {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+
+type ExprContext = Record<string, number | number[] | ((...a: number[]) => number) | Record<string, number>>;
+type Transform = {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+};
+/** A segment: an anchor point plus optional tangent handles (absolute coordinates). */
+type Seg = {
+    anchor: Point;
+    inHandle?: Point;
+    outHandle?: Point;
+};
+/** A subpath: a sequence of segments, open or closed. */
+type Subpath = {
+    closed: boolean;
+    segments: Seg[];
+};
+/** A path: a set of subpaths (contour + holes, multi-piece). */
+type Path = {
+    subpaths: Subpath[];
+};
+/** A closed ring, closing point not duplicated. */
+type Ring = Point[];
+/** A connected polygon: [contour, ...holes]. */
+type PolyGroup = Ring[];
+/** A "material": a set of disjoint polygons (multipolygon). */
+type Shape = PolyGroup[];
+type Stop = {
+    offset: number;
+    color: string;
+};
+/** A Flash-style "tint" color effect: recolors a container toward `color` by `amount` (0..1). */
+type Tint = {
+    color: string;
+    amount: number;
+};
+/** Blend mode (Flash / After Effects style). `add`/`screen` = additive light (glow, mixing); `multiply` = shadow. */
+type BlendMode = 'add' | 'screen' | 'multiply';
+type Paint = {
+    type: 'solid';
+    color: string;
+} | {
+    type: 'linear';
+    angle: number;
+    stops: Stop[];
+    box?: BBox;
+} | {
+    type: 'radial';
+    cx: number;
+    cy: number;
+    r: number;
+    stops: Stop[];
+    box?: BBox;
+};
+/** A region stroke: width + paint (solid OR gradient), cap/join style, dashes. */
+type Stroke = {
+    width: number;
+    paint: Paint;
+    cap?: 'butt' | 'round' | 'square';
+    join?: 'miter' | 'round' | 'bevel';
+    miterLimit?: number;
+    dash?: number[];
+};
+type Filter = {
+    type: 'blur';
+    radius: number;
+} | {
+    type: 'shadow';
+    dx: number;
+    dy: number;
+    blur: number;
+    color: string;
+} | {
+    type: 'glow';
+    blur: number;
+    color: string;
+} | {
+    type: 'adjust';
+    brightness?: number;
+    contrast?: number;
+    saturate?: number;
+    hue?: number;
+};
+/** Easing curve. `cubic` = control points, CSS cubic-bezier style. */
+type Easing = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | {
+    cubic: [number, number, number, number];
+};
+/** Spin direction of a tween (absent = shortest arc). */
+type SpinDir = 'cw' | 'ccw';
+type Keyframe = {
+    frame: number;
+    transform?: Transform;
+    opacity?: number;
+    color?: string;
+    paint?: Paint;
+    tint?: Tint;
+    visible?: boolean;
+    easing?: Easing;
+    rotate?: SpinDir;
+    turns?: number;
+};
+/** Channels animatable by expression (= the decomposed components + opacity). */
+type ExprChannel = 'x' | 'y' | 'scaleX' | 'scaleY' | 'rotation' | 'opacity';
+type TimelineTrack = {
+    id: string;
+    targetId: string;
+    keyframes: Keyframe[];
+    /** Per-channel expressions (`rotation = sin(time)*20`); take priority over interpolation. */
+    expressions?: Partial<Record<ExprChannel, string>>;
+};
+/** Audio clip placed on the timeline: references an asset, starts at `startFrame`. */
+type SoundClip = {
+    id: string;
+    assetId: string;
+    startFrame: number;
+    gain?: number;
+    loop?: boolean;
+    name?: string;
+};
+/** A CONTENT (material) keyframe — frame-by-frame / stop-motion: a snapshot of the drawing. */
+type ContentKey = {
+    frame: number;
+    items: Region[];
+};
+/** Content track of a material layer (frame-by-frame animation, no interpolation). */
+type ContentTrack = {
+    layerId: string;
+    keyframes: ContentKey[];
+};
+type Timeline = {
+    fps: number;
+    durationFrames: number;
+    tracks: TimelineTrack[];
+    /** Frame-by-frame material animation (per layer); HOLD, never tweened. */
+    contentTracks?: ContentTrack[];
+    sounds?: SoundClip[];
+    labels?: FrameLabel[];
+    frameActions?: FrameAction[];
+    onLoad?: Action[];
+    onEnterFrame?: Action[];
+    binds?: InstanceBind[];
+};
+/** Collective binding rule: binds ALL instances of a symbol, with a per-instance index.
+ *  `each "<symbol>" as <as> { opacity = data[i] … }` — the player expands it on load. */
+type InstanceBind = {
+    symbol: string;
+    as: string;
+    expr: Partial<Record<ExprChannel, string>>;
+};
+type PlaybackMode = 'synced' | 'singleFrame' | 'independent';
+type InstancePlayback = {
+    mode: PlaybackMode;
+    frame?: number;
+    speed?: number;
+    loop?: boolean;
+};
+/**
+ * Payload of a `send`: numeric (DSL expression) or textual (`text("itemId")`, the live content of a
+ * Text item). Discriminated for an exact parse/print round-trip.
+ */
+type SendPayload = {
+    kind: 'expr';
+    expr: string;
+} | {
+    kind: 'text';
+    itemId: string;
+};
+type Action = {
+    do: 'play';
+} | {
+    do: 'pause';
+} | {
+    do: 'gotoFrame';
+    frame: number;
+    play?: boolean;
+} | {
+    do: 'gotoLabel';
+    label: string;
+    play?: boolean;
+} | {
+    do: 'setVar';
+    name: string;
+    value: string;
+} | {
+    do: 'setIndex';
+    name: string;
+    index: string;
+    value: string;
+} | {
+    do: 'if';
+    cond: string;
+    then: Action[];
+    else?: Action[];
+} | {
+    do: 'repeat';
+    count: string;
+    body: Action[];
+} | {
+    do: 'repeatRange';
+    var: string;
+    from: string;
+    to: string;
+    body: Action[];
+} | {
+    do: 'call';
+    name: string;
+    args: string[];
+} | {
+    do: 'send';
+    event: string;
+    payload?: SendPayload;
+} | {
+    do: 'sound';
+    assetId: string;
+};
+/** Reusable function: pure value (usable in an expression) or procedure (action block). */
+type FuncDef = {
+    name: string;
+    params: string[];
+} & ({
+    kind: 'value';
+    expr: string;
+} | {
+    kind: 'proc';
+    body: Action[];
+});
+/** Actions triggered when the playhead reaches `frame`. */
+type FrameAction = {
+    frame: number;
+    actions: Action[];
+};
+/** Named marker on the timeline (target of gotoLabel). */
+type FrameLabel = {
+    frame: number;
+    name: string;
+};
+/** Item event: click, hover enter/leave, pointer (press/release/drag/longpress), and `drop`
+ *  (released over a named zone; requires `over`). */
+type ItemEvent = 'click' | 'enter' | 'leave' | 'press' | 'release' | 'drag' | 'longpress' | 'drop';
+/** Interaction: an event on an item triggers actions (Layer B). `over` = named zone (event `drop`). */
+type Interaction = {
+    id: string;
+    targetId: string;
+    event: ItemEvent;
+    over?: string;
+    atPointer?: boolean;
+    actions: Action[];
+};
+/**
+ * "drag" interactor: moves an item with the mouse and writes its position into EXPLICIT variables. A
+ * declarative front-end → produces the same mutations as a hand-written handler. `axis`: 'xy' (both),
+ * 'x' (dragX), 'y' (dragY). `confine` = name of a zone (clamp to its bbox). `grid` = snap.
+ */
+type Interactor = {
+    targetId: string;
+    axis: 'xy' | 'x' | 'y' | 'turn' | 'trace' | 'reveal' | 'link';
+    varX?: string;
+    varY?: string;
+    varT?: string;
+    confine?: string;
+    grid?: number;
+    enabled?: string;
+    pivot?: Point;
+};
+/** Presence + pose of a container at a keyframe (matched by `id` across cels). */
+type Pose = {
+    id: string;
+    transform?: Transform;
+    opacity?: number;
+    tint?: Tint;
+    spin?: SpinDir;
+    turns?: number;
+    filters?: Filter[];
+};
+/** Layer-wide keyframe: the full content of the layer at `frame`. */
+type Cel = {
+    frame: number;
+    poses: Pose[];
+    matter?: Region[];
+    tween?: boolean;
+    shapeTween?: boolean;
+    ease?: Easing;
+};
+/** Per-object interaction state exposed to channel expressions as `self.hovered`/`self.grabbed`/`self.pressed` (0/1). */
+type ItemInteractionState = {
+    hovered: number;
+    grabbed: number;
+    pressed: number;
+};
+/** Resolution context (container expressions + guide layer). `itemState` lets channel expressions read the
+ *  object's own interaction state (`self.hovered`…); the PLAYER provides it, absent elsewhere (flags → 0). */
+type ResolveOpts = {
+    fps?: number;
+    ctx?: ExprContext;
+    guide?: Path;
+    orient?: boolean;
+    parent?: Transform;
+    itemState?: (id: string) => ItemInteractionState | undefined;
+};
+type Region = {
+    id: string;
+    color: string;
+    path: Path;
+    paint?: Paint;
+    stroke?: Stroke;
+    noFill?: boolean;
+    xform?: Transform;
+    opacity?: number;
+    filters?: Filter[];
+    hidden?: boolean;
+    noHit?: boolean;
+};
+/**
+ * GROUP (Ctrl+G, Flash style): a TRANSIENT container — a transform plus its own layers, edited in place
+ * (double-click), movable/tweenable as an object on its parent's track. NOT in the library, not reusable,
+ * and WITHOUT its own internal timeline: to animate the content, turn it into a SYMBOL (F8 → SymbolDef +
+ * Instance). `timeline?` is LEGACY (no longer produced by the editor): kept for reading/rendering old
+ * docs, MIGRATED to a symbol on open (cf. liftAnimatedGroups).
+ */
+type Group = {
+    id: string;
+    kind: 'group';
+    name: string;
+    transform: Transform;
+    layers: Layer[];
+    timeline?: Timeline;
+    opacity?: number;
+    tint?: Tint;
+    hidden?: boolean;
+    noHit?: boolean;
+    pivot?: Point;
+    filters?: Filter[];
+    blend?: BlendMode;
+    hitbox?: {
+        w: number;
+        h: number;
+    };
+    expressions?: Partial<Record<ExprChannel, string>>;
+};
+/** Instance of a reusable symbol: a transform + a reference to the symbol. */
+type Instance = {
+    id: string;
+    kind: 'instance';
+    name: string;
+    transform: Transform;
+    symbolId: string;
+    opacity?: number;
+    tint?: Tint;
+    hidden?: boolean;
+    noHit?: boolean;
+    pivot?: Point;
+    playback?: InstancePlayback;
+    filters?: Filter[];
+    blend?: BlendMode;
+    expressions?: Partial<Record<ExprChannel, string>>;
+};
+/**
+ * Library folder (pure organization, Flash style): a tree by `parent`. SYMBOLS stay FLAT (referenced by
+ * name/id) — a folder does not nest them, it just files them away.
+ */
+type Folder = {
+    id: string;
+    name: string;
+    parent?: string;
+    collapsed?: boolean;
+};
+/** Reusable definition (Flash MovieClip-style symbol) stored in the library. */
+type SymbolDef = {
+    id: string;
+    name: string;
+    layers: Layer[];
+    timeline?: Timeline;
+    folderId?: string;
+};
+/**
+ * "live" (editable) text: a leaf item animatable like a container (transform/opacity/tint, pivot). LOCAL
+ * origin = top-left corner; text flows toward (box.w, box.h). `box` = measured extent (updated by the
+ * editor via measureText) → pure bbox/hit without a canvas.
+ */
+type Text = {
+    id: string;
+    kind: 'text';
+    name: string;
+    transform: Transform;
+    content: string;
+    font: string;
+    size: number;
+    align: 'left' | 'center' | 'right';
+    lineHeight: number;
+    color: string;
+    weight?: number;
+    italic?: boolean;
+    box: {
+        w: number;
+        h: number;
+    };
+    wrap?: boolean;
+    bind?: string;
+    decimals?: number;
+    /** `id` explicitly set by the author via `text "…" as "<id>"` (≠ auto-generated id). Drives the
+     *  printing of `as` in the flatFormat DSL. */
+    idExplicit?: boolean;
+    opacity?: number;
+    tint?: Tint;
+    hidden?: boolean;
+    noHit?: boolean;
+    pivot?: Point;
+    filters?: Filter[];
+    blend?: BlendMode;
+    expressions?: Partial<Record<ExprChannel, string>>;
+};
+/** Bitmap image: a leaf item animatable like text. References an asset; `w`/`h` = intrinsic size in px
+ * (local coords, origin = top-left corner). */
+type Image = {
+    id: string;
+    kind: 'image';
+    name: string;
+    transform: Transform;
+    assetId: string;
+    w: number;
+    h: number;
+    opacity?: number;
+    tint?: Tint;
+    hidden?: boolean;
+    noHit?: boolean;
+    pivot?: Point;
+    filters?: Filter[];
+    blend?: BlendMode;
+    expressions?: Partial<Record<ExprChannel, string>>;
+};
+/** Layer content: material, one-off group, symbol instance, text, or image. */
+type Item = Region | Group | Instance | Text | Image;
+/** Embedded asset (media) — the `Doc.assets` registry. `data` = base64 data-URI (media) or raw SVG text ('svg'). */
+type Asset = {
+    id: string;
+    kind: 'image' | 'audio' | 'video' | 'font' | 'svg';
+    name: string;
+    mime: string;
+    data: string;
+};
+type Layer = {
+    id: string;
+    name: string;
+    visible: boolean;
+    locked: boolean;
+    opacity: number;
+    items: Item[];
+    cels?: Cel[];
+    isFolder?: boolean;
+    parent?: string;
+    collapsed?: boolean;
+    isMask?: boolean;
+    maskOff?: boolean;
+    isGuide?: boolean;
+    orientToGuide?: boolean;
+};
+type Doc = {
+    width: number;
+    height: number;
+    background?: string;
+    layers: Layer[];
+    symbols: SymbolDef[];
+    folders?: Folder[];
+    assets?: Asset[];
+    timeline?: Timeline;
+    variables?: Record<string, number | number[]>;
+    imports?: string[];
+    functions?: FuncDef[];
+    interactions?: Interaction[];
+    interactors?: Interactor[];
+};
+/** Edit-navigation step (breadcrumb): a one-off group or an entry into a symbol. */
+type EditFrame = {
+    kind: 'group';
+    id: string;
+    name: string;
+} | {
+    kind: 'symbol';
+    symbolId: string;
+    name: string;
+};
+type Tool = 'brush' | 'rect' | 'ellipse' | 'eraser' | 'fill' | 'select' | 'transform' | 'text' | 'pan' | 'pen' | 'pathselect' | 'ink';
+
+export type { Action, Asset, BBox, BlendMode, Cel, ContentKey, ContentTrack, Doc, Easing, EditFrame, ExprChannel, ExprContext, Filter, Folder, FrameAction, FrameLabel, FuncDef, Group, Image, Instance, InstanceBind, InstancePlayback, Interaction, Interactor, Item, ItemEvent, ItemInteractionState, Keyframe, Layer, Paint, Path, PlaybackMode, Point, PolyGroup, Polygon, Pose, Region, ResolveOpts, Ring, Seg, SendPayload, Shape, SoundClip, SpinDir, Stop, Stroke, Subpath, SymbolDef, Text, Timeline, TimelineTrack, Tint, Tool, Transform };

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@flatkit/types",
+  "version": "0.1.0",
+  "description": "Shared types for the FlatInk format (Doc, Layer, Item, …). The leaf of the dependency graph.",
+  "license": "MIT",
+  "author": "Zwyk Studio",
+  "homepage": "http://flatink.zwyk-studio.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zwykstudio/flatkit.git",
+    "directory": "packages/types"
+  },
+  "bugs": "https://github.com/zwykstudio/flatkit/issues",
+  "keywords": [
+    "flatink",
+    "flatpack",
+    "animation",
+    "types"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "module": "./dist/index.js"
+}