machinalayout 0.2.0 → 0.3.1

package/README.md

@@ -55,6 +55,8 @@ Machina adapters ask you to learn one layout model: Machina records. The framewo
 - React Native: `machinalayout/text/react-native`
 - Vue DOM: `machinalayout/text/vue`
 
+Inspection and handoff utilities are available at `machinalayout/inspect` and `machinalayout/handoff`.
+
 Subpath imports are preferred for adapters/renderers. Root imports remain valid during `0.x` compatibility windows.
 
 Framework peers are adapter-specific (`react`/`react-dom`, `react-native`, `vue`) based on the subpaths you use.
@@ -79,6 +81,7 @@ Normal users should not need to learn each framework's layout/template box-drawi
 - bounded `z`
 - named layers
 - layout interpolation helpers
+- stack geometry/content query helpers
 
 ### React
 
@@ -116,6 +119,17 @@ Normal users should not need to learn each framework's layout/template box-drawi
 
 Named layers organize paint order over the existing bounded `z` system. Layers are not portals.
 
+
+## Docs index
+
+- [Row model](docs/row-model.md)
+- [Frames and stack](docs/frames-and-stack.md)
+- [Grid arrange](docs/grid-arrange.md)
+- [Stack geometry helpers](docs/stack-geometry-helpers.md)
+- [Screen catalog and viewport matrix](docs/screen-catalog-and-viewports.md)
+- [Inspection and handoff bundles](docs/inspection-and-handoff.md)
+- [Error codes](docs/error-codes.md)
+
 ## Tiny `LayoutRow[]` example
 
 ```ts
@@ -383,4 +397,5 @@ This repo uses Biome.
 - [Z-order and containment](docs/z-order-and-containment.md)
 - [Error code reference](docs/error-codes.md)
 - [MachinaDispatch runtime guide](docs/machina-dispatch.md)
+- [DeusMachina behavioral kernel and framework bindings](docs/deusmachina.md)
 - Dispatch sample: [`samples/dispatch-counter`](samples/dispatch-counter/README.md) (uses `machinalayout/dispatch`)

package/dist/MachinaReactView-Bau5bErA.d.ts

@@ -0,0 +1,41 @@
+import React from 'react';
+import { M as MachinaDebugOverlayMode } from './debugOverlay-fWLv1cS7.js';
+import { R as ResolvedLayoutDocument, N as NodeId, a as Rect, b as ResolvedLayoutNode } from './types-CYgsjDai.js';
+
+type MachinaSlotProps<TViewData = unknown, TNodeData = unknown> = {
+    id: NodeId;
+    rect: Rect;
+    debugLabel?: string;
+    node: ResolvedLayoutNode;
+    viewKey?: string;
+    viewData?: TViewData;
+    nodeData?: TNodeData;
+};
+type MachinaRenderLayer = {
+    z: number;
+};
+type MachinaReactDebugOverlayOptions = {
+    mode?: MachinaDebugOverlayMode;
+    labels?: boolean;
+    borders?: boolean;
+    selectedNodeId?: string;
+};
+type MachinaReactViewProps = {
+    layout: ResolvedLayoutDocument;
+    views?: Record<string, React.ComponentType<MachinaSlotProps>>;
+    viewData?: Record<string, unknown>;
+    nodeData?: Record<NodeId, unknown>;
+    className?: string;
+    style?: React.CSSProperties;
+    nodeClassName?: string;
+    debug?: boolean;
+    nodeContainment?: "none" | "layout-paint" | "strict";
+    nodeContentVisibility?: "none" | "auto";
+    nodeContainIntrinsicSize?: string;
+    layers?: Record<string, MachinaRenderLayer>;
+    defaultLayer?: string;
+    debugOverlay?: MachinaReactDebugOverlayOptions;
+};
+declare function MachinaReactView(props: MachinaReactViewProps): React.JSX.Element;
+
+export { type MachinaReactDebugOverlayOptions as M, MachinaReactView as a, type MachinaReactViewProps as b, type MachinaSlotProps as c };

package/dist/chunk-2ZQ2RFFI.js

@@ -0,0 +1,400 @@
+// src/deus/types.ts
+var DeusMachinaError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DeusMachinaError";
+  }
+  code;
+};
+
+// src/deus/utility.ts
+function finite(value, code, label) {
+  if (!Number.isFinite(value)) throw new DeusMachinaError(code, `${label} must be finite`);
+  return value;
+}
+function judgeUtility(context, candidates, options = {}) {
+  if (options.hysteresis !== void 0 && (!Number.isFinite(options.hysteresis) || options.hysteresis < 0)) {
+    throw new DeusMachinaError("InvalidHysteresis", "hysteresis must be finite and >= 0");
+  }
+  const results = candidates.map((candidate, index) => {
+    const eligible = candidate.when?.(context) ?? true;
+    const score = eligible ? finite(
+      typeof candidate.score === "function" ? candidate.score(context) : candidate.score,
+      "InvalidUtilityScore",
+      `utility score for ${candidate.key}`
+    ) : 0;
+    const reason = typeof candidate.reason === "function" ? candidate.reason(context) : candidate.reason;
+    return {
+      key: candidate.key,
+      eligible,
+      score,
+      index,
+      ...reason !== void 0 ? { reason } : null
+    };
+  });
+  let selected = results.filter((r) => r.eligible).reduce(
+    (best, r) => best === null || r.score > best.score ? r : best,
+    null
+  );
+  if (selected && options.previousKey !== void 0 && options.hysteresis !== void 0) {
+    const previous = results.find((r) => r.key === options.previousKey && r.eligible);
+    if (previous && selected.key !== previous.key && selected.score - previous.score < options.hysteresis)
+      selected = previous;
+  }
+  return { selected, candidates: results };
+}
+
+// src/deus/machine.ts
+function assertValidDeusPath(path, label) {
+  if (!Array.isArray(path) || path.length === 0) {
+    throw new DeusMachinaError("InvalidDeusPath", `${label} must be a non-empty path`);
+  }
+  path.forEach((segment, index) => {
+    if (typeof segment !== "string" || segment.length === 0 || segment.trim().length === 0) {
+      throw new DeusMachinaError(
+        "InvalidDeusPath",
+        `${label} segment ${index} must be a non-empty string`
+      );
+    }
+  });
+}
+function formatDeusPath(path) {
+  assertValidDeusPath(path, "path");
+  return path.join("/");
+}
+function sameDeusPath(a, b) {
+  assertValidDeusPath(a, "left path");
+  assertValidDeusPath(b, "right path");
+  return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+function isDeusAncestorPath(ancestor, path) {
+  assertValidDeusPath(ancestor, "ancestor path");
+  assertValidDeusPath(path, "path");
+  return ancestor.length <= path.length && ancestor.every((v, i) => v === path[i]);
+}
+function finite2(value, code, label) {
+  if (!Number.isFinite(value)) throw new DeusMachinaError(code, `${label} must be finite`);
+  return value;
+}
+function pathKey(path) {
+  return formatDeusPath(path);
+}
+function validateReason(reason, code, label) {
+  if (reason !== void 0 && typeof reason !== "string" && typeof reason !== "function") {
+    throw new DeusMachinaError(code, `${label} reason must be a string or function`);
+  }
+}
+function defineDeusMachine(machine) {
+  if (!machine || typeof machine !== "object") {
+    throw new DeusMachinaError("InvalidDeusMachine", "machine must be an object");
+  }
+  assertValidDeusPath(machine.initial, "initial");
+  if (!Array.isArray(machine.states)) {
+    throw new DeusMachinaError("InvalidDeusMachine", "states must be an array");
+  }
+  if (!Array.isArray(machine.transitions)) {
+    throw new DeusMachinaError("InvalidDeusMachine", "transitions must be an array");
+  }
+  const stateKeys = /* @__PURE__ */ new Set();
+  const states = machine.states.map((s) => {
+    assertValidDeusPath(s.path, "state path");
+    const key = pathKey(s.path);
+    if (stateKeys.has(key))
+      throw new DeusMachinaError("DuplicateDeusStatePath", `duplicate state path ${key}`);
+    stateKeys.add(key);
+    return { ...s, path: [...s.path] };
+  });
+  if (!stateKeys.has(pathKey(machine.initial)))
+    throw new DeusMachinaError("UnknownDeusStatePath", "initial path must exist");
+  const transitionKeys = /* @__PURE__ */ new Set();
+  const transitions = machine.transitions.map((t) => {
+    if (typeof t.key !== "string" || t.key.length === 0 || t.key.trim().length === 0)
+      throw new DeusMachinaError("InvalidDeusTransition", "transition keys must be non-empty");
+    if (transitionKeys.has(t.key))
+      throw new DeusMachinaError("DuplicateDeusTransitionKey", `duplicate transition key ${t.key}`);
+    transitionKeys.add(t.key);
+    assertValidDeusPath(t.from, `transition ${t.key} from`);
+    if (!stateKeys.has(pathKey(t.from)))
+      throw new DeusMachinaError(
+        "UnknownDeusStatePath",
+        `transition ${t.key} from path must exist`
+      );
+    if (Array.isArray(t.to)) {
+      assertValidDeusPath(t.to, `transition ${t.key} to`);
+      if (!stateKeys.has(pathKey(t.to)))
+        throw new DeusMachinaError(
+          "UnknownDeusStatePath",
+          `transition ${t.key} to path must exist`
+        );
+    } else if (t.to !== void 0 && typeof t.to !== "function") {
+      throw new DeusMachinaError(
+        "InvalidDeusTransition",
+        `transition ${t.key} to must be a path or function`
+      );
+    }
+    if (typeof t.score === "number")
+      finite2(t.score, "InvalidDeusTransition", `transition ${t.key} score`);
+    validateReason(t.reason, "InvalidDeusTransition", `transition ${t.key}`);
+    if (t.hysteresis !== void 0) {
+      if (typeof t.hysteresis.previous !== "function")
+        throw new DeusMachinaError(
+          "InvalidHysteresis",
+          `transition ${t.key} hysteresis.previous must be a function`
+        );
+      finite2(t.hysteresis.margin, "InvalidHysteresis", `transition ${t.key} hysteresis margin`);
+      if (t.hysteresis.margin < 0)
+        throw new DeusMachinaError(
+          "InvalidHysteresis",
+          `transition ${t.key} hysteresis margin must be >= 0`
+        );
+    }
+    const utilityKeys = /* @__PURE__ */ new Set();
+    for (const u of t.utility ?? []) {
+      if (typeof u.key !== "string" || u.key.length === 0 || u.key.trim().length === 0)
+        throw new DeusMachinaError(
+          "InvalidDeusTransition",
+          `transition ${t.key} utility key must be non-empty`
+        );
+      if (utilityKeys.has(u.key))
+        throw new DeusMachinaError("DuplicateUtilityKey", `duplicate utility key ${u.key}`);
+      utilityKeys.add(u.key);
+      if (typeof u.score !== "number" && typeof u.score !== "function")
+        throw new DeusMachinaError(
+          "InvalidUtilityScore",
+          `utility score for ${u.key} must be a number or function`
+        );
+      if (typeof u.score === "number")
+        finite2(u.score, "InvalidUtilityScore", `utility score for ${u.key}`);
+      validateReason(u.reason, "InvalidDeusTransition", `utility ${u.key}`);
+    }
+    return { ...t, from: [...t.from], to: Array.isArray(t.to) ? [...t.to] : t.to };
+  });
+  return { initial: [...machine.initial], states, transitions };
+}
+function createDeusSnapshot(machine, board) {
+  return { state: [...machine.initial], board, stepIndex: 0 };
+}
+function stepDeusMachine(machine, snapshot, event) {
+  const stateBefore = [...snapshot.state];
+  assertValidDeusPath(stateBefore, "snapshot state");
+  const stateMap = new Map(machine.states.map((s) => [pathKey(s.path), s]));
+  const orderedFrom = stateBefore.map((_, i) => stateBefore.slice(0, stateBefore.length - i));
+  const candidates = orderedFrom.flatMap(
+    (from) => machine.transitions.map((t) => ({ t })).filter(({ t }) => sameDeusPath(t.from, from))
+  );
+  const traces = [];
+  let selected;
+  candidates.forEach(({ t }, index) => {
+    const eventMatches = t.event === void 0 || t.event === event.type;
+    let eligible = eventMatches && (t.when?.(snapshot.board, event) ?? true);
+    let utility;
+    let utilityKey;
+    let score = eligible ? t.score === void 0 ? 1 : finite2(
+      typeof t.score === "function" ? t.score(snapshot.board, event) : t.score,
+      "InvalidDeusTransition",
+      `transition ${t.key} score`
+    ) : 0;
+    if (eligible && t.utility) {
+      utility = judgeUtility(
+        { board: snapshot.board, event },
+        t.utility.map((u) => ({
+          key: u.key,
+          when: (ctx) => u.when?.(ctx.board, ctx.event) ?? true,
+          score: (ctx) => typeof u.score === "function" ? u.score(ctx.board, ctx.event) : u.score,
+          reason: typeof u.reason === "function" ? (ctx) => {
+            const reason2 = u.reason;
+            return typeof reason2 === "function" ? reason2(ctx.board, ctx.event) : "";
+          } : u.reason
+        })),
+        t.hysteresis ? { previousKey: t.hysteresis.previous(snapshot.board), hysteresis: t.hysteresis.margin } : void 0
+      );
+      if (!utility.selected) eligible = false;
+      else {
+        utilityKey = utility.selected.key;
+        if (t.score === void 0) score = utility.selected.score;
+      }
+    }
+    const to = eligible && t.to ? typeof t.to === "function" ? [...t.to(snapshot.board, event)] : [...t.to] : void 0;
+    if (to) {
+      assertValidDeusPath(to, `transition ${t.key} to`);
+      if (!stateMap.has(pathKey(to)))
+        throw new DeusMachinaError(
+          "UnknownDeusStatePath",
+          `transition ${t.key} to path must exist`
+        );
+    }
+    const reason = typeof t.reason === "function" ? t.reason(snapshot.board, event) : t.reason;
+    const trace = {
+      key: t.key,
+      from: [...t.from],
+      ...to ? { to } : null,
+      event: t.event,
+      eligible,
+      score: eligible ? score : 0,
+      index,
+      ...reason !== void 0 ? { reason } : null,
+      ...utility ? { utility } : null
+    };
+    traces.push(trace);
+    if (eligible && (!selected || trace.score > selected.trace.score))
+      selected = { trace, t, utilityKey };
+  });
+  if (!selected)
+    return {
+      snapshot: { state: stateBefore, board: snapshot.board, stepIndex: snapshot.stepIndex + 1 },
+      trace: { stateBefore, stateAfter: stateBefore, event: event.type, transitions: traces }
+    };
+  const target = selected.trace.to ?? stateBefore;
+  const common = stateBefore.findIndex((v, i) => target[i] !== v);
+  const prefix = common === -1 ? Math.min(stateBefore.length, target.length) : common;
+  for (let i = stateBefore.length; i > prefix; i--)
+    stateMap.get(pathKey(stateBefore.slice(0, i)))?.onExit?.(snapshot.board, event);
+  if (selected.utilityKey)
+    selected.t.utility?.find((u) => u.key === selected?.utilityKey)?.do?.(snapshot.board, event);
+  selected.t.do?.(snapshot.board, event);
+  for (let i = prefix + 1; i <= target.length; i++)
+    stateMap.get(pathKey(target.slice(0, i)))?.onEnter?.(snapshot.board, event);
+  return {
+    snapshot: { state: [...target], board: snapshot.board, stepIndex: snapshot.stepIndex + 1 },
+    trace: {
+      stateBefore,
+      stateAfter: [...target],
+      event: event.type,
+      selectedTransition: selected.trace,
+      transitions: traces
+    }
+  };
+}
+function formatDeusStepTrace(trace) {
+  const selected = trace.selectedTransition ? trace.selectedTransition.key : "none";
+  return `${formatDeusPath(trace.stateBefore)} --${trace.event}/${selected}--> ${formatDeusPath(trace.stateAfter)}`;
+}
+
+// src/deus/debugOverlay.ts
+var collapsed = ["debugOverlay", "collapsed"];
+var overlay = ["debugOverlay", "nonInteractiveOverlay"];
+var panel = ["debugOverlay", "interactivePanel"];
+function createMachinaDebugOverlayMachine() {
+  return defineDeusMachine({
+    initial: collapsed,
+    states: [
+      {
+        path: collapsed,
+        onEnter: (b) => {
+          b.mode = "collapsed";
+          b.selectedNodeId = void 0;
+        }
+      },
+      {
+        path: overlay,
+        onEnter: (b) => {
+          b.mode = "nonInteractiveOverlay";
+        }
+      },
+      {
+        path: panel,
+        onEnter: (b) => {
+          b.mode = "interactivePanel";
+        }
+      }
+    ],
+    transitions: [
+      { key: "collapsed.showOverlay", from: collapsed, event: "showOverlay", to: overlay },
+      {
+        key: "overlay.openPanel",
+        from: overlay,
+        event: "openPanel",
+        to: panel,
+        do: (b, e) => {
+          if (e.type === "openPanel") b.selectedNodeId = e.nodeId;
+        }
+      },
+      { key: "panel.showOverlay", from: panel, event: "showOverlay", to: overlay },
+      { key: "overlay.collapse", from: overlay, event: "collapse", to: collapsed },
+      { key: "panel.collapse", from: panel, event: "collapse", to: collapsed },
+      {
+        key: "overlay.toggleLabels",
+        from: overlay,
+        event: "toggleLabels",
+        do: (b) => {
+          b.labels = !b.labels;
+        }
+      },
+      {
+        key: "panel.toggleLabels",
+        from: panel,
+        event: "toggleLabels",
+        do: (b) => {
+          b.labels = !b.labels;
+        }
+      },
+      {
+        key: "overlay.toggleBorders",
+        from: overlay,
+        event: "toggleBorders",
+        do: (b) => {
+          b.borders = !b.borders;
+        }
+      },
+      {
+        key: "panel.toggleBorders",
+        from: panel,
+        event: "toggleBorders",
+        do: (b) => {
+          b.borders = !b.borders;
+        }
+      },
+      {
+        key: "panel.selectNode",
+        from: panel,
+        event: "selectNode",
+        do: (b, e) => {
+          if (e.type === "selectNode") b.selectedNodeId = e.nodeId;
+        }
+      }
+    ]
+  });
+}
+function getMachinaDebugOverlayBehavior(board) {
+  if (board.mode === "collapsed")
+    return {
+      visible: false,
+      pointerEvents: "none",
+      consumesLayoutSpace: false,
+      showPanel: false,
+      showLabels: false,
+      showBorders: false
+    };
+  if (board.mode === "nonInteractiveOverlay")
+    return {
+      visible: true,
+      pointerEvents: "none",
+      consumesLayoutSpace: false,
+      showPanel: false,
+      showLabels: board.labels,
+      showBorders: board.borders
+    };
+  return {
+    visible: true,
+    pointerEvents: "auto",
+    consumesLayoutSpace: true,
+    showPanel: true,
+    showLabels: board.labels,
+    showBorders: board.borders
+  };
+}
+
+export {
+  DeusMachinaError,
+  judgeUtility,
+  formatDeusPath,
+  sameDeusPath,
+  isDeusAncestorPath,
+  defineDeusMachine,
+  createDeusSnapshot,
+  stepDeusMachine,
+  formatDeusStepTrace,
+  createMachinaDebugOverlayMachine,
+  getMachinaDebugOverlayBehavior
+};

package/dist/chunk-33CKBEJH.js

@@ -0,0 +1,186 @@
+import {
+  MachinaLayoutError
+} from "./chunk-VREK57S3.js";
+
+// src/screenCatalog.ts
+var STANDARD_VIEWPORTS = [
+  { key: "desktop", width: 1440, height: 900, label: "Desktop", tags: ["desktop"] },
+  { key: "tablet", width: 1024, height: 768, label: "Tablet", tags: ["tablet"] },
+  { key: "phone", width: 390, height: 844, label: "Phone", tags: ["phone", "mobile"] }
+];
+function isPositiveFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function validateStringArray(value, code, field) {
+  if (value === void 0) return;
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    throw new MachinaLayoutError(code, `${field} must be an array of strings`);
+  }
+}
+function copyViewport(viewport) {
+  return {
+    ...viewport,
+    tags: viewport.tags === void 0 ? void 0 : [...viewport.tags]
+  };
+}
+function copyScreen(screen) {
+  return {
+    ...screen,
+    viewports: screen.viewports === void 0 ? void 0 : [...screen.viewports],
+    tags: screen.tags === void 0 ? void 0 : [...screen.tags]
+  };
+}
+function defineMachinaViewports(viewports) {
+  const seen = /* @__PURE__ */ new Set();
+  return viewports.map((viewport) => {
+    if (typeof viewport.key !== "string" || viewport.key.trim() === "") {
+      throw new MachinaLayoutError("InvalidViewport", "viewport key must be a non-empty string");
+    }
+    if (seen.has(viewport.key)) {
+      throw new MachinaLayoutError(
+        "DuplicateViewportKey",
+        `duplicate viewport key: ${viewport.key}`
+      );
+    }
+    seen.add(viewport.key);
+    if (!isPositiveFiniteNumber(viewport.width) || !isPositiveFiniteNumber(viewport.height)) {
+      throw new MachinaLayoutError(
+        "InvalidViewport",
+        `viewport ${viewport.key} width and height must be finite positive numbers`
+      );
+    }
+    if (viewport.deviceScaleFactor !== void 0 && !isPositiveFiniteNumber(viewport.deviceScaleFactor)) {
+      throw new MachinaLayoutError(
+        "InvalidViewport",
+        `viewport ${viewport.key} deviceScaleFactor must be a finite positive number`
+      );
+    }
+    if (viewport.label !== void 0 && typeof viewport.label !== "string") {
+      throw new MachinaLayoutError(
+        "InvalidViewport",
+        `viewport ${viewport.key} label must be a string`
+      );
+    }
+    validateStringArray(viewport.tags, "InvalidViewport", `viewport ${viewport.key} tags`);
+    return copyViewport(viewport);
+  });
+}
+function createViewportMatrix(preset = "standard-responsive") {
+  if (preset === "desktop-only") return defineMachinaViewports([STANDARD_VIEWPORTS[0]]);
+  if (preset === "mobile-first")
+    return defineMachinaViewports([
+      STANDARD_VIEWPORTS[2],
+      STANDARD_VIEWPORTS[1],
+      STANDARD_VIEWPORTS[0]
+    ]);
+  return defineMachinaViewports(STANDARD_VIEWPORTS);
+}
+function defineMachinaScreens(screens) {
+  const catalog = { screens: {}, order: [] };
+  for (const screen of screens) {
+    if (typeof screen.key !== "string" || screen.key.trim() === "") {
+      throw new MachinaLayoutError("InvalidScreen", "screen key must be a non-empty string");
+    }
+    if (catalog.screens[screen.key] !== void 0) {
+      throw new MachinaLayoutError("DuplicateScreenKey", `duplicate screen key: ${screen.key}`);
+    }
+    if (typeof screen.route !== "string" || screen.route.trim() === "") {
+      throw new MachinaLayoutError(
+        "InvalidScreen",
+        `screen ${screen.key} route must be a non-empty string`
+      );
+    }
+    if (screen.fixture !== void 0 && typeof screen.fixture !== "string") {
+      throw new MachinaLayoutError(
+        "InvalidScreen",
+        `screen ${screen.key} fixture must be a string`
+      );
+    }
+    validateStringArray(screen.viewports, "InvalidScreen", `screen ${screen.key} viewports`);
+    validateStringArray(screen.tags, "InvalidScreen", `screen ${screen.key} tags`);
+    if (screen.metadata !== void 0 && (typeof screen.metadata !== "object" || screen.metadata === null || Array.isArray(screen.metadata))) {
+      throw new MachinaLayoutError(
+        "InvalidScreen",
+        `screen ${screen.key} metadata must be an object`
+      );
+    }
+    catalog.screens[screen.key] = copyScreen(screen);
+    catalog.order.push(screen.key);
+  }
+  return catalog;
+}
+function slugMachinaArtifactName(input) {
+  const slug = input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug === "" ? "artifact" : slug;
+}
+function getMachinaViewport(viewports, key) {
+  const viewport = viewports.find((candidate) => candidate.key === key);
+  if (!viewport) throw new MachinaLayoutError("UnknownViewportKey", `unknown viewport key: ${key}`);
+  return viewport;
+}
+function orderedUnique(values) {
+  const result = [];
+  for (const value of values ?? []) {
+    if (!result.includes(value)) result.push(value);
+  }
+  return result;
+}
+function expandScreenViewportTasks(catalog, viewports, options = {}) {
+  const viewportKeys = viewports.map((viewport) => viewport.key);
+  const viewportKeySet = new Set(viewportKeys);
+  for (const key of options.screenKeys ?? []) {
+    if (catalog.screens[key] === void 0)
+      throw new MachinaLayoutError("UnknownScreenKey", `unknown screen key: ${key}`);
+  }
+  for (const key of options.viewportKeys ?? []) {
+    if (!viewportKeySet.has(key))
+      throw new MachinaLayoutError("UnknownViewportKey", `unknown viewport key: ${key}`);
+  }
+  const requestedScreens = options.screenKeys === void 0 ? void 0 : new Set(options.screenKeys);
+  const requestedViewports = options.viewportKeys === void 0 ? void 0 : new Set(options.viewportKeys);
+  const tasks = [];
+  for (const screenKey of catalog.order) {
+    if (requestedScreens && !requestedScreens.has(screenKey)) continue;
+    const screen = catalog.screens[screenKey];
+    if (!screen)
+      throw new MachinaLayoutError(
+        "UnknownScreenKey",
+        `unknown screen key in catalog order: ${screenKey}`
+      );
+    const screenViewportSet = screen.viewports === void 0 ? void 0 : new Set(screen.viewports);
+    for (const key of screen.viewports ?? []) {
+      if (!viewportKeySet.has(key))
+        throw new MachinaLayoutError(
+          "UnknownViewportKey",
+          `screen ${screen.key} references unknown viewport key: ${key}`
+        );
+    }
+    for (const viewport of viewports) {
+      if (screenViewportSet && !screenViewportSet.has(viewport.key)) continue;
+      if (requestedViewports && !requestedViewports.has(viewport.key)) continue;
+      const tags = orderedUnique([...screen.tags ?? [], ...viewport.tags ?? []]);
+      if ((options.tags ?? []).some((tag) => !tags.includes(tag))) continue;
+      tasks.push({
+        key: `${screen.key}__${viewport.key}`,
+        screenKey: screen.key,
+        viewportKey: viewport.key,
+        route: screen.route,
+        fixture: screen.fixture,
+        viewport,
+        screen,
+        tags,
+        artifactBaseName: `${slugMachinaArtifactName(screen.key)}__${slugMachinaArtifactName(viewport.key)}`
+      });
+    }
+  }
+  return tasks;
+}
+
+export {
+  defineMachinaViewports,
+  createViewportMatrix,
+  defineMachinaScreens,
+  slugMachinaArtifactName,
+  getMachinaViewport,
+  expandScreenViewportTasks
+};