@dojo-video-engine/layout 0.0.0-stage → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dojo Video Engine contributors
+
+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/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @dojo-video-engine/layout
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@dojo-video-engine/layout` is Dojo Video Engine's bounded semantic authoring layer for
+stacks, wrapping rows/columns, grids, overlays, intrinsic sizing, safe areas,
+and small sibling-relative constraints. It compiles a flat plan over existing
+child IDs into ordinary numeric Scene v1 geometry.
+
+It is not a second render format. Plans are transient authoring input; the
+compiler returns a valid Scene v1 and the renderer, player, export worker, and
+stored project continue to consume only that Scene.
+
+The compiled Scene is a target-size-specific render projection, not responsive
+authoring source. An editor that needs to reflow later must retain the original
+source Scene plus its LayoutPlan(s) and recompile those for the new target.
+Never keep only the compiled projection as the sole editable source: its
+semantic `hug`/`fill`/track/constraint intent has deliberately compiled away.
+
+```ts
+import { compileLayout, item, row } from "@dojo-video-engine/layout";
+
+const plan = row({
+  items: [
+    item("portrait", { width: "fill", aspectRatio: 1 }),
+    item("copy", { width: "fill" }),
+  ],
+  gap: "4%",
+  padding: { x: "6%", y: "5%" },
+  align: "center",
+});
+
+const result = compileLayout(scene, plan, {
+  textMetrics,
+  mediaMetrics,
+  missingMediaMetrics: { mode: "error" },
+  fontFallbackPolicy: "allow-system", // deterministic projects use a font asset
+});
+```
+
+## Contract
+
+The public tool shape is deliberately flat and non-recursive:
+
+- `containerId` is `$root` or one existing Scene node;
+- every `items[].id` names one direct visual child;
+- item order controls flow and grid auto-placement without reordering Scene
+  paint order;
+- `layout.kind` is `stack`, `grid`, or `overlay`;
+- `row()` and `column()` are typed sugar for `stack` axes;
+- sizes are fixed pixels, percentages, `hug`, or `fill`;
+- grow/shrink, min/max, aspect ratio, margins, gaps, wrapping, distribution,
+  grid spans, overlay anchors, and bounded sibling constraints are explicit;
+- safe-area and padding insets are resolved against the target container;
+- output children have numeric `position`, `left`, `top`, `width`, and
+  `height` and no stale Scene-v1 geometry fields.
+
+`layoutPlanSchema` and `validateLayoutPlan()` own the complete runtime contract.
+`layoutPlanJsonSchema()` exposes its generated draft-07 structural shape and
+adds kind-specific conditions, so tool validators reject fields a layout kind
+cannot consume. Draft-07 cannot express uniqueness by an object's `id` value;
+every tool host must still call `validateLayoutPlan()` before compilation.
+`tryCompileLayout()` returns portable structured failures; `compileLayout()`
+throws `LayoutCompileError`.
+
+## Intrinsic metrics
+
+The compiler uses core's prepared, synchronous `TextMetricsProvider` and
+`MediaMetricsProvider`. Every measurement reports field-level `exact`,
+`declared`, or `estimated` provenance. Media with missing intrinsic dimensions
+never receives a hidden default: choose `mode: "error"` or provide explicit
+type-specific fallback sizes.
+
+Text planning defaults to `fontFallbackPolicy: "require-prepared"`. Family
+lists are parsed in author order and the first family matching a declared font
+asset is compiled to that exact asset id; the id itself must be representable
+as one unambiguous Scene font family (spaces are safe, comma/quote escapes are
+not). A prepared text-metrics provider is also required. `"allow-system"` is an
+explicit portability escape hatch and always emits estimated font evidence
+plus a warning.
+
+Layout v2 text resolves an omitted direction through its bundled deterministic
+first-strong scan; explicit `ltr`/`rtl` wins and host-dependent `inherit` is
+rejected. Rich runs are rejected for intrinsic fitting by default; the
+legacy-unsafe opt-in is intentionally visible. Fixed boxes can still carry
+legacy rich text because no v2 shaping decision is made.
+Successful item measurements retain the detached text plan—source cluster
+ranges, planned lines/ellipsis, fit status, direction, and provenance—so an
+editor or agent can explain the compiled Scene-v1 text.
+
+The bundled cluster segmenter covers combining marks, emoji modifiers/ZWJ,
+regional-indicator flags, and CRLF without depending on host Unicode data. It
+is deliberately not a complete UAX #29 implementation for modern Indic
+conjunct chains without explicit ZWJ or decomposed Hangul Jamo; prefer
+precomposed/shaped input for those cases.
+
+## Determinism and limits
+
+Grid auto-placement is stable and non-dense; declared cells reserve their spans
+before auto placement. Implicit row tracks fill the bounded grid, while column
+auto-flow requires explicit rows so guard budgets never affect geometry. Grid
+stretch applies only to `fill` or omitted/auto item sizes, never explicit fixed
+sizes. Sibling constraints form a
+bounded dependency DAG; unknown targets, cycles, multiple writers, collisions,
+and out-of-bounds constrained results are errors. Plans, tracks, constraints,
+text, solver steps, and coordinates all have host-tightenable budgets.
+
+Semantic layout is a target-size snapshot. Recompile the same source Scene and
+plan for portrait, square, or landscape output. Keep that source/plan pair for
+future edits; the projection alone cannot recover semantic intent. Animating compiler-owned
+geometry is rejected: retaining and reevaluating semantic layout per frame
+would require a future Scene version and is outside this Scene v1 compiler.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export * from "./schema.js";
+export * from "./types.js";
+export * from "./text.js";
+export { compileLayout, tryCompileLayout } from "./solver.js";
+import { type GridLayout, type LayoutItem, type LayoutPlan, type OverlayLayout, type StackLayout } from "./schema.js";
+export type LayoutItemOptions = Omit<LayoutItem, "id">;
+/** Detached ergonomic item descriptor for TypeScript authoring. */
+export declare function item(id: string, options?: LayoutItemOptions): LayoutItem;
+type StackPlanOptions = Omit<StackLayout, "kind" | "axis"> & {
+    containerId?: string;
+    items: LayoutItem[];
+};
+/** Canonical one-dimensional layout constructor. */
+export declare function stack(axis: "row" | "column", options: StackPlanOptions): LayoutPlan;
+export declare function row(options: StackPlanOptions): LayoutPlan;
+export declare function column(options: StackPlanOptions): LayoutPlan;
+type GridPlanOptions = Omit<GridLayout, "kind"> & {
+    containerId?: string;
+    items: LayoutItem[];
+};
+export declare function grid(options: GridPlanOptions): LayoutPlan;
+type OverlayPlanOptions = Omit<OverlayLayout, "kind"> & {
+    containerId?: string;
+    items: LayoutItem[];
+};
+export declare function overlay(options: OverlayPlanOptions): LayoutPlan;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;AAEvD,mEAAmE;AACnE,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAE5E;AAED,KAAK,gBAAgB,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB,CAAC;AAEF,oDAAoD;AACpD,wBAAgB,KAAK,CACnB,IAAI,EAAE,KAAK,GAAG,QAAQ,EACtB,OAAO,EAAE,gBAAgB,GACxB,UAAU,CAMZ;AAED,wBAAgB,GAAG,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,CAEzD;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,CAE5D;AAED,KAAK,eAAe,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB,CAAC;AAEF,wBAAgB,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,UAAU,CAKzD;AAED,KAAK,kBAAkB,GAAG,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB,CAAC;AAEF,wBAAgB,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU,CAK/D"}

package/dist/index.js

@@ -0,0 +1,48 @@
+export * from "./schema.js";
+export * from "./types.js";
+export * from "./text.js";
+export { compileLayout, tryCompileLayout } from "./solver.js";
+import { LAYOUT_CONTRACT_VERSION, LAYOUT_ROOT, layoutPlanSchema, } from "./schema.js";
+/** Detached ergonomic item descriptor for TypeScript authoring. */
+export function item(id, options = {}) {
+    return structuredClone({ id, ...options });
+}
+/** Canonical one-dimensional layout constructor. */
+export function stack(axis, options) {
+    return makePlan(options.containerId, options.items, {
+        ...withoutPlanFields(options),
+        kind: "stack",
+        axis,
+    });
+}
+export function row(options) {
+    return stack("row", options);
+}
+export function column(options) {
+    return stack("column", options);
+}
+export function grid(options) {
+    return makePlan(options.containerId, options.items, {
+        ...withoutPlanFields(options),
+        kind: "grid",
+    });
+}
+export function overlay(options) {
+    return makePlan(options.containerId, options.items, {
+        ...withoutPlanFields(options),
+        kind: "overlay",
+    });
+}
+function makePlan(containerId, items, layout) {
+    return layoutPlanSchema.parse({
+        layoutVersion: LAYOUT_CONTRACT_VERSION,
+        containerId: containerId ?? LAYOUT_ROOT,
+        layout,
+        items,
+    });
+}
+function withoutPlanFields(value) {
+    const { containerId: _containerId, items: _items, ...rest } = value;
+    return rest;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,gBAAgB,GAMjB,MAAM,aAAa,CAAC;AAIrB,mEAAmE;AACnE,MAAM,UAAU,IAAI,CAAC,EAAU,EAAE,UAA6B,EAAE;IAC9D,OAAO,eAAe,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;AAC7C,CAAC;AAOD,oDAAoD;AACpD,MAAM,UAAU,KAAK,CACnB,IAAsB,EACtB,OAAyB;IAEzB,OAAO,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,EAAE;QAClD,GAAG,iBAAiB,CAAC,OAAO,CAAC;QAC7B,IAAI,EAAE,OAAO;QACb,IAAI;KACL,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,OAAyB;IAC3C,OAAO,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAyB;IAC9C,OAAO,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAClC,CAAC;AAOD,MAAM,UAAU,IAAI,CAAC,OAAwB;IAC3C,OAAO,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,EAAE;QAClD,GAAG,iBAAiB,CAAC,OAAO,CAAC;QAC7B,IAAI,EAAE,MAAM;KACb,CAAC,CAAC;AACL,CAAC;AAOD,MAAM,UAAU,OAAO,CAAC,OAA2B;IACjD,OAAO,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,EAAE;QAClD,GAAG,iBAAiB,CAAC,OAAO,CAAC;QAC7B,IAAI,EAAE,SAAS;KAChB,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CACf,WAA+B,EAC/B,KAAmB,EACnB,MAA4B;IAE5B,OAAO,gBAAgB,CAAC,KAAK,CAAC;QAC5B,aAAa,EAAE,uBAAuB;QACtC,WAAW,EAAE,WAAW,IAAI,WAAW;QACvC,MAAM;QACN,KAAK;KACN,CAAC,CAAC;AACL,CAAC;AAED,SAAS,iBAAiB,CAExB,KAAQ;IACR,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IACpE,OAAO,IAAI,CAAC;AACd,CAAC"}