@playabl/sdk 1.0.0 → 1.1.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,6 +8,13 @@ Browser SDK for Playabl games providing parent-platform communication, game stat
8
8
  npm install @playabl/sdk
9
9
  ```
10
10
 
11
+ While 1.1.0 is in beta the stable tag still resolves to 1.0.0; `@playabl/sdk/layout` and
12
+ the layout types are on the `beta` dist-tag:
13
+
14
+ ```bash
15
+ npm install @playabl/sdk@beta
16
+ ```
17
+
11
18
  `sdk.game` and `sdk.devtools` need runtime 1.0.0 or newer in the environment the game loads from. That runtime is live on dev, staging and production.
12
19
 
13
20
  ## Usage
@@ -175,6 +182,24 @@ if (sdk.audio.isSupported()) {
175
182
  }
176
183
  ```
177
184
 
185
+ ### Layout keys in Node tools
186
+
187
+ Build tools that read `layout.json` from disk import the runtime's own synthesis from the `@playabl/sdk/layout` subpath. It runs in plain Node and never loads the runtime; games do not import it. It first ships in 1.1.0-beta.0. Pin the exact version: a change to the role table reaches your tool only when you move the pin.
188
+
189
+ ```typescript
190
+ import { DEFAULT_FRAME, synthesiseLayout } from '@playabl/sdk/layout'
191
+
192
+ const { items, entries } = synthesiseLayout(layout, tweaksSchema, {}, DEFAULT_FRAME)
193
+ ```
194
+
195
+ It is an ES module: `import` loads it anywhere, and `require()` on Node 20.19+ or 22.12+. TypeScript finds its types with `moduleResolution` set to `node16`, `nodenext` or `bundler` in an ES module project, and only with `nodenext` (TypeScript 5.8 or newer) in a CommonJS one; `node10` does not read `exports`, so it is not supported. Besides `synthesiseLayout` and `DEFAULT_FRAME`, it exports the role table (`LAYOUT_ROLES`, `LAYOUT_ANCHORS`, `LAYOUT_WEIGHTS`, `LAYOUT_ALIGNS`, `ENTRY_FIELDS`), `layoutKey`, `defaultPrefix` and `roleLimits`; every table is frozen.
196
+
197
+ ### Runtime resolution
198
+
199
+ Most games never configure the runtime. Call `configure({ runtimeUrl })` or `configure({ manifestUrl })` before any other SDK call to import a specific runtime build or read a specific manifest.
200
+
201
+ A page can instead name its environment's manifest in `window.__PLAYABL_MANIFEST_URL__`, set before any module script runs. The Playabl workspace preview does this: it is served from `localhost` but belongs to dev, staging or production, so without it the wrapper would take `localhost` for SDK development and import its build-time fallback runtime. The order is `configure({ runtimeUrl })`, `configure({ manifestUrl })`, a valid `?env=` on the game URL (`?env=local` keeps the fallback), the global, then the hostname. The global is used only when it is a string holding an `https:` URL on `cdn.playabl.ai`, `cdn-staging.playabl.ai` or `cdn-dev.playabl.ai` on the default port; any other value is ignored with one console warning. It needs 1.1.0-beta.1 or newer.
202
+
178
203
  ## API Surface
179
204
 
180
205
  - `sdk.ready()` - Connects to the Playabl parent iframe host.
@@ -184,5 +209,6 @@ if (sdk.audio.isSupported()) {
184
209
  - `sdk.tweaks.init(schema)` - Registers live-tunable values controlled by the host.
185
210
  - `sdk.assets.register(mapping)` - Registers game assets so the host can replace them.
186
211
  - `sdk.audio` - Creates Web Audio contexts with an iOS Safari silent-mode patch.
212
+ - `@playabl/sdk/layout` - `synthesiseLayout` and the layout role table, for Node tools that read `layout.json`.
187
213
 
188
214
 
package/dist/index.d.ts CHANGED
@@ -40,6 +40,7 @@ type CellGridHooks = Required<Pick<ContentHooks, 'blankLevel' | 'placeInLevel' |
40
40
  * coordinates or origins also refuse. Pure and synchronous, as every content
41
41
  * hook must be; nothing here needs the runtime, so a game can call it while
42
42
  * building its vocabulary.
43
+ * A game that declares `describeScene().grid` with `cols`/`rows` needs none of this: the runtime's board profile (runtime 1.6.0+) supplies the three hooks itself; this helper stays for games on the raw-hook path.
43
44
  */
44
45
  declare function cellGridHooks({ cell, origin, key, }?: CellGridOptions): CellGridHooks;
45
46
 
@@ -115,6 +116,13 @@ interface TweakValueRejection {
115
116
  interface TweaksInitOptions {
116
117
  /** The contents of `src/tweaks.values.json`. Missing → `{}`. */
117
118
  values?: TweakValues;
119
+ /**
120
+ * The contents of `src/layout.json`. Each role of each entry becomes an
121
+ * ordinary tweak (`hudScoreFontSize` for `fontSize` of `def:hud-score`),
122
+ * merged before `values` and the host's values apply. A bad entry or role
123
+ * is dropped with a warning; a key `tweaks.json` already has is never replaced.
124
+ */
125
+ layout?: LayoutFile;
118
126
  }
119
127
  interface PlayablTweaks {
120
128
  readonly values: Readonly<Record<string, TweakValue>>;
@@ -122,6 +130,11 @@ interface PlayablTweaks {
122
130
  subscribe(key: string, cb: (value: TweakValue, prev: TweakValue) => void): () => void;
123
131
  onChange(cb: (key: string, value: TweakValue, prev: TweakValue) => void): () => void;
124
132
  snapshot(): Record<string, TweakValue>;
133
+ /**
134
+ * The current value of each role the `layout.json` entry `id` has — for a
135
+ * canvas-drawn element and the `text` role. `undefined` for an id with no entry.
136
+ */
137
+ layout(id: string): LayoutValues | undefined;
125
138
  }
126
139
  type AssetType = 'image' | 'audio' | 'video' | 'unknown';
127
140
  type AssetStatus = 'original' | 'overridden';
@@ -407,6 +420,53 @@ type CatalogCategory = 'characters' | 'hazards' | 'pickups' | 'world' | 'effects
407
420
  type LayoutRole = 'anchor' | 'x' | 'y' | 'w' | 'h' | 'rotation' | 'scale' | 'opacity' | 'z' | 'fontSize' | 'fontWeight' | 'align' | 'font' | 'padding' | 'radius' | 'text' | 'color' | 'background' | 'visible';
408
421
  /** `{ role: tweakKey }` — each role names the tweak that holds that property. */
409
422
  type LayoutRoleMap = Partial<Record<LayoutRole, string>>;
423
+ /**
424
+ * One `src/layout.json` entry: the roles one HUD or screen element has, each
425
+ * with its value. Loose on purpose — a JSON import types `anchor` as `string`,
426
+ * and the runtime checks every value, dropping a bad one with a warning.
427
+ */
428
+ interface LayoutEntry {
429
+ /** 1–40 characters; each synthesised tweak's `name` is `"<label> · <Role>"`. */
430
+ label?: string;
431
+ /**
432
+ * Replaces the key prefix derived from the id (`def:hud-score` → `hudScore`). Must be
433
+ * camelCase: one that is not skips the entry with a warning, with no fallback. Required
434
+ * when the id's first segment starts with a digit (`def:2-player`): the entry is skipped
435
+ * with a warning without it.
436
+ */
437
+ prefix?: string;
438
+ /** The faces the `font` control offers; without it, only the declared `font`. */
439
+ fonts?: string[];
440
+ /**
441
+ * `true` for an element the game draws itself (on a canvas) from
442
+ * `tweaks.layout(id)`: no element will carry its id, so Creator Tools never
443
+ * report it as not wired.
444
+ */
445
+ canvas?: boolean;
446
+ anchor?: string;
447
+ x?: number;
448
+ y?: number;
449
+ w?: number;
450
+ h?: number;
451
+ rotation?: number;
452
+ scale?: number;
453
+ opacity?: number;
454
+ z?: number;
455
+ fontSize?: number;
456
+ fontWeight?: string;
457
+ align?: string;
458
+ font?: string;
459
+ padding?: number;
460
+ radius?: number;
461
+ text?: string;
462
+ color?: string;
463
+ background?: string;
464
+ visible?: boolean;
465
+ }
466
+ /** `src/layout.json`: one entry per element the creator may move, size or restyle, keyed by its `def:` catalog id. */
467
+ type LayoutFile = Record<string, LayoutEntry>;
468
+ /** `tweaks.layout(id)`: each role the entry has, with its current value. */
469
+ type LayoutValues = Partial<Record<LayoutRole, TweakValue>>;
410
470
  type ContentOwner = 'ai' | 'creator';
411
471
  interface ContentGroup {
412
472
  id: string;
@@ -417,11 +477,25 @@ interface ContentLevel {
417
477
  /** `lv_<n>` when minted by the engine; any non-empty string is tolerated from disk. */
418
478
  id: string;
419
479
  name: string;
420
- /** Names an entry in `ContentDocument.groups`. */
480
+ /** Names an entry in `ContentDocument.groups`. Absent only on a level a file had before every level had to be in a group; the engine never makes one (PLA-1849). */
421
481
  group?: string;
422
482
  owner: ContentOwner;
423
483
  /** Opaque to the engine: a plain JSON object or array. */
424
484
  payload: Record<string, unknown> | unknown[];
485
+ /**
486
+ * Present while the game's `acceptPayload` refuses this level's payload:
487
+ * the verdict taken right after the engine's last edit of it. Always last.
488
+ */
489
+ refusal?: LevelRefusal;
490
+ }
491
+ /**
492
+ * A level `acceptPayload` refused after an edit (PLA-1842). The edit stands;
493
+ * the mark says the level is not playable as it is. `reason` is the game's,
494
+ * one line of at most 200 UTF-16 code units, absent when it gave none.
495
+ * Runtime 1.4.5 or newer.
496
+ */
497
+ interface LevelRefusal {
498
+ reason?: string;
425
499
  }
426
500
  interface ContentDocument {
427
501
  version: 1;
@@ -443,6 +517,13 @@ interface ContentFieldSpec {
443
517
  options?: string[];
444
518
  /** Informational only — never substituted for a missing payload key. */
445
519
  default?: number | string | boolean;
520
+ /**
521
+ * `text` only: a `def:` id with a drawable `layout.json` entry. The SDK
522
+ * writes the active level's value of this field into every element marked
523
+ * with that id. On `name` the value is `level.name`, and the spec is not
524
+ * listed in `catalog.content.fields`.
525
+ */
526
+ layout?: string;
446
527
  }
447
528
  type ContentFieldValue = string | number | boolean | null;
448
529
  /**
@@ -475,6 +556,27 @@ interface LevelPreview {
475
556
  rows: number;
476
557
  cells: LevelPreviewCell[];
477
558
  }
559
+ /** The two layers a placed instance can be on; two of one layer never share a cell. */
560
+ type BoardLayer = 'floor' | 'object';
561
+ /**
562
+ * One placed instance of a level on a board the runtime owns (a game whose
563
+ * `describeScene()` returns a `grid` with `cols` / `rows` and writes fewer
564
+ * than the three placement hooks — a hook the game wrote keeps its verb, and
565
+ * the runtime supplies the rest): `payload.instances[]`. `x` / `y` are the
566
+ * top-left cell; `w` / `h` are written only when they differ from the
567
+ * definition's `footprint`. Every other field is the game's and passes
568
+ * through every mutation untouched.
569
+ */
570
+ interface BoardInstance {
571
+ /** Minted by the runtime (`i_<n>`, unique in the level, never from its position), or whatever the file holds. */
572
+ id: string;
573
+ defId: string;
574
+ x: number;
575
+ y: number;
576
+ w?: number;
577
+ h?: number;
578
+ [field: string]: unknown;
579
+ }
478
580
  /** A uniform placement grid over `[x, y, x+w, y+h]`, in game CSS px. */
479
581
  interface SceneGrid {
480
582
  x: number;
@@ -484,6 +586,13 @@ interface SceneGrid {
484
586
  cols: number;
485
587
  rows: number;
486
588
  }
589
+ /**
590
+ * Why the runtime's own board refused `place` / `content-move-instance` /
591
+ * `content-remove-instance`: a cell already held by an instance of the same
592
+ * layer, a second instance of a `singleton` definition, or the last instance
593
+ * of a `required` one. A refusal for any other reason carries none.
594
+ */
595
+ type ContentRefusalCause = 'occupied' | 'singleton' | 'required';
487
596
  /** The level the game reports as current; placement targets its `id`. */
488
597
  interface StateLevel {
489
598
  id: string;
@@ -507,6 +616,13 @@ interface CatalogEntryBase {
507
616
  nodeKinds: string[];
508
617
  /** Basename only. */
509
618
  sprite?: string;
619
+ /**
620
+ * The `assets.json` key `sprite` was resolved through — set only when the
621
+ * builder's `sprite` option named a key, never for a file name. It may name
622
+ * a key `catalog.assets` does not list (a legacy video); fall back to
623
+ * `sprite` then.
624
+ */
625
+ assetId?: string;
510
626
  singleton: boolean;
511
627
  }
512
628
  interface CatalogLevel extends CatalogEntryBase {
@@ -518,14 +634,65 @@ interface CatalogLevel extends CatalogEntryBase {
518
634
  contentId?: string;
519
635
  /** `{ name, group, ...declared }`, engine-attached by `contentId` lookup; never from `catalog()`. */
520
636
  fields?: Record<string, ContentFieldValue>;
637
+ /** The document level's mark (PLA-1842), engine-attached by `contentId` lookup; never from `catalog()`. */
638
+ refusal?: LevelRefusal;
521
639
  preview?: LevelPreview;
522
640
  }
523
641
  type CatalogScreen = CatalogEntryBase;
524
642
  interface CatalogDefinition extends CatalogEntryBase {
643
+ /**
644
+ * The frame's `name` inside the sprite sheet `sprite` names (its
645
+ * `<image>.frames.json`). Present exactly when `sprite` is; basename only.
646
+ */
647
+ spriteFrame?: string;
525
648
  category?: CatalogCategory;
526
649
  layout?: LayoutRoleMap;
527
650
  /** Drag/drop into a level writes a durable instance through `content.hooks.placeInLevel`. */
528
651
  placeable?: 'content';
652
+ /**
653
+ * The cells a placed instance covers, `[w, h]`, positive integers. On the
654
+ * wire it is present on every `placeable: "content"` definition, resolved
655
+ * to `[1, 1]` when undeclared, and absent on every other.
656
+ */
657
+ footprint?: [number, number];
658
+ /**
659
+ * Which instances a placed instance may share cells with: two instances of
660
+ * one layer never overlap, an `object` may sit on a `floor`. Present on the
661
+ * wire for every placeable definition (`"object"` when undeclared).
662
+ */
663
+ layer?: BoardLayer;
664
+ /** Whether the Creator may resize an instance's footprint. Present on the wire for every placeable definition (`false` when undeclared). */
665
+ resizable?: boolean;
666
+ /** A level keeps at least one instance of this definition: removing the last refuses. Present on the wire for every placeable definition (`false` when undeclared). */
667
+ required?: boolean;
668
+ /**
669
+ * Buttons the Creator shows on this definition's card. On the wire every item
670
+ * is checked and the array is never empty; the value `definition()` returns
671
+ * is the author's array, unchecked.
672
+ */
673
+ actions?: CatalogEntryAction[];
674
+ /**
675
+ * The catalog screen this definition is drawn on: the one whose id its
676
+ * `def:screen-<screen id>-…` id continues, the longest such
677
+ * (`def:screen-<screen id>` itself included), or `null`. The runtime stamps
678
+ * it on every definition it sends, replacing any value the game gave.
679
+ */
680
+ screen?: string | null;
681
+ }
682
+ /**
683
+ * A button the Creator shows on a definition's card that fires a game
684
+ * command. `preview` — an effect's one-shot demo — is the one kind.
685
+ */
686
+ interface CatalogEntryAction {
687
+ kind: 'preview';
688
+ /**
689
+ * A `commands` id. The Creator enables the button only when the catalog
690
+ * advertises it; the runtime does not check.
691
+ */
692
+ command: string;
693
+ label?: string;
694
+ /** Sent as the command's payload. */
695
+ args?: Record<string, string | number | boolean>;
529
696
  }
530
697
  interface SceneRect {
531
698
  x: number;
@@ -545,12 +712,146 @@ interface SceneNode {
545
712
  instance: Record<string, unknown>;
546
713
  /** Top level only. Marks a placed content instance; equals the instance id the placement hooks returned. */
547
714
  contentId?: string;
715
+ /**
716
+ * SDK-stamped on an interface node the runtime derived from an element
717
+ * carrying `data-layout-instance`: the attribute's trimmed value, usually
718
+ * the content id of what the element shows, the node's id then being
719
+ * `<key>@<value>` (`def:hud-card@lv_3` carries `lv_3`). A game-supplied one
720
+ * is ignored. Never `contentId`, which marks a placed level piece.
721
+ */
722
+ instanceKey?: string;
723
+ /**
724
+ * SDK-stamped on a node whose definition a level field is bound to: spread
725
+ * it into `content-set-field { ...levelField, value }`. A game-supplied one
726
+ * is ignored.
727
+ */
728
+ levelField?: {
729
+ id: string;
730
+ field: string;
731
+ };
732
+ /**
733
+ * SDK-stamped on a node whose definition declares a `text` layout role, or
734
+ * has a level field bound to it, when the runtime could read the copy: how
735
+ * it is set on the page now. A game-supplied one is ignored. It needs a
736
+ * runtime with the scene text stamp.
737
+ */
738
+ text?: TextStyleStamp;
739
+ }
740
+ /**
741
+ * The type of the copy a scene node's element holds, read from the live DOM
742
+ * when the `scene` is sent. Every length is in game CSS px: the computed
743
+ * values untransformed, `box` in the space of the node's `rect`, so a host
744
+ * turns the first into rendered px with `scale`. None is sent for a holder that
745
+ * is rotated or skewed. Not carried, though each can move a line break:
746
+ * `text-wrap-style` (`balance`, `pretty`), `word-break`, `overflow-wrap`,
747
+ * `hyphens` and `font-variation-settings`; where the game sets one, a host that
748
+ * lays the copy out greedily can break lines elsewhere.
749
+ */
750
+ interface TextStyleStamp {
751
+ /** The computed `font-family`, verbatim: the game's own stack. */
752
+ fontFamily: string;
753
+ /**
754
+ * The first family of `fontFamily` the game document can actually render, as
755
+ * one CSS family token: a generic keyword (`system-ui`), a plain name
756
+ * (`PlayablProbe`) or a name in double quotes (`"Bree Serif"`). A host that
757
+ * has a face the game lacks, its own Inter, sets copy in this family so it
758
+ * wraps as the game's does. A family counts when this copy's characters are
759
+ * set differently in front of the stack after it than by that stack alone,
760
+ * in advance or in the shape of the glyphs, a web face as well as an
761
+ * installed one: an installed Arabic family with no Latin letters is named
762
+ * for Arabic copy, and skipped for Latin letters, though not for a space or
763
+ * digit it holds, which the game draws in the first family that has them.
764
+ * One that sets the copy as wide as the next family but draws other glyphs
765
+ * (a CJK face against a serif) is named, not the one after it, and a web
766
+ * face the game has not used, or whose unicode-range leaves the copy out, is
767
+ * skipped. One token cannot say that copy in two scripts is drawn in two
768
+ * families, and names the first. Absent when no family of the stack
769
+ * resolves, or a face of one that this copy needs (its weight, its style,
770
+ * the slice its characters fall in) is still loading; use `fontFamily` then.
771
+ */
772
+ renderedFamily?: string;
773
+ fontWeight: string;
774
+ fontStyle: string;
775
+ fontSizePx: number;
776
+ /**
777
+ * The line pitch: the computed `line-height` when it is a px length, else
778
+ * measured from the lines themselves (never from the holder's box, which can
779
+ * be taller than its copy).
780
+ */
781
+ lineHeightPx: number;
782
+ /** 0 when the computed value is `normal`, or a percentage the engine leaves unresolved. */
783
+ letterSpacingPx: number;
784
+ /** 0 when the computed value is `normal`, or a percentage the engine leaves unresolved. */
785
+ wordSpacingPx: number;
786
+ /**
787
+ * The computed `text-indent` of the block container the copy sits in, when it
788
+ * is a px length, else 0. An inline holder that shares its lines with other
789
+ * content carries 0: the indent acts on the block's first line, and the
790
+ * holder's place along it is already in `box.x`.
791
+ */
792
+ textIndentPx: number;
793
+ /** The computed `font-stretch`, verbatim. */
794
+ fontStretch: string;
795
+ /** The computed `font-kerning`, verbatim. */
796
+ fontKerning: string;
797
+ /** The computed `font-variant`, verbatim. */
798
+ fontVariant: string;
799
+ /** The computed `font-feature-settings`, verbatim: `normal` when there are none. */
800
+ fontFeatureSettings: string;
801
+ textTransform: string;
802
+ /**
803
+ * The computed `text-align` of the block container the copy sits in: for an
804
+ * inline holder, its block's, since the property acts on block containers.
805
+ */
806
+ textAlign: string;
807
+ direction: 'ltr' | 'rtl';
808
+ whiteSpace: string;
809
+ /** Line boxes the copy occupies now, at least 1. */
810
+ lines: number;
811
+ /**
812
+ * Whether copy typed here breaks onto a new line at `box.w` as it grows: the
813
+ * holder's `white-space` allows wrapping, and the copy either already
814
+ * occupies two lines or the box `box.x` and `box.w` come from has a width
815
+ * that does not follow its copy. That is a block-level box in flow, not
816
+ * floated and not a flex or grid item (past any `display: contents`
817
+ * wrapper), and, whatever its display and position, one measured wider than
818
+ * its one line of copy by more than 1px: an absolutely positioned box with a
819
+ * width, a stretched flex or grid item, a flex item that grows to its row. A
820
+ * box held as wide as its `min-width`, or one that shares its line with other
821
+ * content, is not counted. An inline-block, a float, an absolutely positioned
822
+ * box and a flex or grid item that sizes to its copy are as wide as it. A
823
+ * field that wraps only at `lines >= 2` scrolls sideways while a one-line
824
+ * title is typed.
825
+ */
826
+ wraps: boolean;
827
+ /**
828
+ * Where the copy sits, as `rect` is measured. `x` and `w` are the content
829
+ * box (border box less border and padding) of the holder, which wraps the
830
+ * copy; when the holder is `display: inline`, whose own box is the union of
831
+ * its line fragments, or `contents`, which has none, they are the content box
832
+ * of the nearest ancestor that is neither, the block its lines sit in, but
833
+ * only when the holder's words are all that is in those lines. Sharing them
834
+ * (words, an icon or image, `::before` or `::after` content), the copy starts
835
+ * partway along the line, so they are the span of the holder's own words.
836
+ * `y` and `h` are the copy's own line boxes, `lines` times `lineHeightPx`,
837
+ * even where the holder's box is taller than its copy or, for an inline
838
+ * holder, shorter than its line. `w` and `h` are at least 2: the runtime
839
+ * sends no stamp for a smaller box.
840
+ */
841
+ box: SceneRect;
842
+ /**
843
+ * Rendered size over layout size of the holder: 1 untransformed. Read on both
844
+ * sides; no stamp is sent when they disagree (a rotation or skew).
845
+ */
846
+ scale: number;
548
847
  }
549
848
  interface CatalogEntryOptions {
550
849
  tweakKeys?: string[];
551
850
  nodeKinds?: string[];
552
851
  /**
553
- * An `assets.json` key; resolved to a basename through the merged mapping.
852
+ * An `assets.json` key, resolved to a basename through the merged mapping
853
+ * and recorded as the entry's `assetId`; or a bare image file name, which
854
+ * gets no `assetId`. A value that is neither is dropped with a warning.
554
855
  * `| undefined` on purpose: authors write `sprite: spriteFor('KEY')`, and
555
856
  * `spriteFor` returns `undefined` for an unknown key — under
556
857
  * `exactOptionalPropertyTypes` that would otherwise be a type error.
@@ -564,10 +865,34 @@ interface CatalogLevelOptions extends CatalogEntryOptions {
564
865
  preview?: LevelPreview | undefined;
565
866
  }
566
867
  interface CatalogDefinitionOptions extends CatalogEntryOptions {
868
+ /**
869
+ * The frame this definition uses inside the sheet `sprite` names — a `name`
870
+ * from that sheet's `<image>.frames.json`. Omitted or `""`, it defaults to the
871
+ * definition id without its `def:` prefix (`def:lily` → `"lily"`), so a sheet
872
+ * whose frames are named after the definitions that use them needs nothing
873
+ * here. Ignored without `sprite`; a path (`/` or `\`) is dropped with a warning.
874
+ */
875
+ spriteFrame?: string | undefined;
876
+ /** Defaults to `false` for a `placeable: 'content'` definition and `true` for any other. */
567
877
  singleton?: boolean;
568
878
  category?: CatalogCategory;
569
879
  layout?: LayoutRoleMap;
570
880
  placeable?: 'content';
881
+ /** Cells a placed instance covers; `[1, 1]` when omitted. Read only with `placeable: 'content'`. */
882
+ footprint?: [number, number] | undefined;
883
+ /** `'object'` when omitted. Read only with `placeable: 'content'`. */
884
+ layer?: BoardLayer | undefined;
885
+ /** `false` when omitted. Read only with `placeable: 'content'`. */
886
+ resizable?: boolean | undefined;
887
+ /** `false` when omitted. Read only with `placeable: 'content'`. */
888
+ required?: boolean | undefined;
889
+ /**
890
+ * Buttons the Creator shows on this definition's card — for an `effects`
891
+ * definition, `[{ kind: 'preview', command: 'preview-splash' }]`. A malformed
892
+ * item is dropped with a warning; the legacy `audition` kind is dropped
893
+ * silently.
894
+ */
895
+ actions?: CatalogEntryAction[] | undefined;
571
896
  }
572
897
  /** The helpers the runtime hands to `catalog(ctx)`. */
573
898
  interface CatalogContext {
@@ -636,12 +961,32 @@ interface ContentHooks {
636
961
  /**
637
962
  * Required for `content-set-payload` — the verb is advertised only when this
638
963
  * exists (D19), because the engine cannot judge a game's payload shape.
639
- * Runs against a clone of the proposed payload: `false` refuses; the hook
640
- * may normalize the clone in place; anything else accepts.
964
+ * Runs against a clone of the proposed payload: `false` refuses; a
965
+ * `PayloadRefusal` refuses and says why; the hook may normalize the clone in
966
+ * place; anything else accepts. A refusal's `reason`, or the message the hook
967
+ * threw, becomes the verb's `command-refused.reason`.
968
+ *
969
+ * It also judges every payload an accepted edit produces, and every level on
970
+ * intake (PLA-1842; runtime 1.4.5 or newer): a refusal there never refuses
971
+ * the edit, it marks the level `refusal`. That clone is discarded, so a hook
972
+ * that has to change it to accept it marks the level too, without a reason.
641
973
  */
642
974
  acceptPayload?(payload: unknown, meta: {
643
975
  id: string;
644
- }): boolean | void;
976
+ }): boolean | void | PayloadRefusal;
977
+ }
978
+ /**
979
+ * `acceptPayload`'s refusal with a reason: exactly `accept: false` and an
980
+ * optional string `reason`, as own data properties, in a new object (never
981
+ * the payload clone the hook was handed). Any other key makes it an ordinary
982
+ * return, which accepts. The reason is sent as one line of at most 200 UTF-16
983
+ * code units (control characters become spaces; longer text is cut with `…`);
984
+ * a `reason` that is not a string is ignored and reported. Runtime 1.4.3 or
985
+ * newer: an older runtime accepts the payload.
986
+ */
987
+ interface PayloadRefusal {
988
+ accept: false;
989
+ reason?: string;
645
990
  }
646
991
  /** `content: { document, hooks, fields }` on `devtools.js` — opt-in. */
647
992
  interface DevtoolsContent {
@@ -669,8 +1014,20 @@ interface DevtoolsVocabulary {
669
1014
  definitions?: CatalogDefinition[];
670
1015
  progression?: CatalogProgression;
671
1016
  };
1017
+ /**
1018
+ * What the runtime cannot see from the page: the `grid` and the objects drawn
1019
+ * on a canvas. Every element marked `data-layout` whose `layout.json` entry is
1020
+ * drawn on the page and names a catalog definition is derived by the runtime,
1021
+ * which owns its identity and rect: a node listed here for one leaves the
1022
+ * scene and contributes at most its `instance`. Optional for a game with such
1023
+ * an entry, which gets a scene of its interface without it. A runtime of
1024
+ * 1.4.8 or older derives nothing and reports only the nodes listed here.
1025
+ * `nodes` is optional for a game whose pieces the runtime's board places
1026
+ * (runtime 1.6.0+): `{ grid }` alone, with a well-formed grid, lists the
1027
+ * active level's instances; a malformed grid alone keeps the previous scene.
1028
+ */
672
1029
  describeScene?(): {
673
- nodes: SceneNode[];
1030
+ nodes?: SceneNode[];
674
1031
  grid?: SceneGrid;
675
1032
  };
676
1033
  describeInstance?(nodeId: string): Record<string, unknown> | null | undefined;
@@ -722,7 +1079,8 @@ type RuntimeLoader = () => Promise<PlayablSDK>;
722
1079
  /**
723
1080
  * Override runtime resolution. `runtimeUrl` imports a specific runtime build
724
1081
  * directly; `manifestUrl` points at a specific manifest. Both bypass the
725
- * automatic environment detection — useful for QA or self-hosting.
1082
+ * automatic environment detection and `window.__PLAYABL_MANIFEST_URL__` —
1083
+ * useful for QA or self-hosting.
726
1084
  */
727
1085
  declare function configure(options: {
728
1086
  runtimeUrl?: string;
@@ -735,4 +1093,4 @@ declare const __testing: {
735
1093
  setRuntimeLoader(loader: RuntimeLoader): void;
736
1094
  };
737
1095
 
738
- export { type AssetDescriptor, type AssetEntry, type AssetKind, type AssetOverride, type AssetRecipe, type AssetStatus, type AssetType, type AssetValueEntry, type AssetsMapping, type AssetsRegisterOptions, type AssetsUrlMap, type AssetsValues, type BooleanTweak, type CameraAPI, type CameraOptions, type CameraResult, type CatalogCategory, type CatalogContext, type CatalogDefinition, type CatalogDefinitionOptions, type CatalogEntryBase, type CatalogEntryOptions, type CatalogLevel, type CatalogLevelOptions, type CatalogProgression, type CatalogScreen, type CellGridEntry, type CellGridHooks, type CellGridOptions, type ColorTweak, type ContentDocument, type ContentFieldSpec, type ContentFieldType, type ContentFieldValue, type ContentGroup, type ContentHandle, type ContentHooks, type ContentLevel, type ContentOwner, type ContentVerbType, type DevtoolsCommand, type DevtoolsContent, type DevtoolsHandle, type DevtoolsVocabulary, type EnumTweak, type ErrorCode, type FileSystemAPI, type FileSystemOptions, type FileSystemResult, type GameLoopHooks, type GameMode, type GameRunHandle, type GameRunOptions, type GeolocationAPI, type GeolocationOptions, type GeolocationResult, type HapticsAPI, type LayoutRole, type LayoutRoleMap, type LevelPreview, type LevelPreviewCell, type MicrophoneAPI, type MicrophoneRecordOptions, type MicrophoneResult, type MicrophoneStreamOptions, type MotionAttitude, type MotionData, type MotionRotation, type MotionVector, type NormalizedAssetEntry, type NumberTweak, type OrientationData, type PlayablAssets, type PlayablAudio, type PlayablAudioAutoPauseOptions, type PlayablAudioContext, type PlayablAudioOptions, type PlayablDevice, type PlayablDevtools, PlayablError, type PlayablGame, type PlayablSDK, type PlayablTweaks, type ProgressionNoun, type ProgressionShape, type ReadyResult, type SaveResult, type SceneGrid, type SceneNode, type SceneRect, type SensorsAPI, type StateLevel, type SubmitResult, type TextTweak, type TweakAppliesOn, type TweakSchema, type TweakSchemaItem, type TweakType, type TweakValue, type TweakValueIssue, type TweakValueRejection, type TweakValues, type TweaksInitOptions, __testing, cellGridHooks, configure, sdk as default };
1096
+ export { type AssetDescriptor, type AssetEntry, type AssetKind, type AssetOverride, type AssetRecipe, type AssetStatus, type AssetType, type AssetValueEntry, type AssetsMapping, type AssetsRegisterOptions, type AssetsUrlMap, type AssetsValues, type BoardInstance, type BoardLayer, type BooleanTweak, type CameraAPI, type CameraOptions, type CameraResult, type CatalogCategory, type CatalogContext, type CatalogDefinition, type CatalogDefinitionOptions, type CatalogEntryAction, type CatalogEntryBase, type CatalogEntryOptions, type CatalogLevel, type CatalogLevelOptions, type CatalogProgression, type CatalogScreen, type CellGridEntry, type CellGridHooks, type CellGridOptions, type ColorTweak, type ContentDocument, type ContentFieldSpec, type ContentFieldType, type ContentFieldValue, type ContentGroup, type ContentHandle, type ContentHooks, type ContentLevel, type ContentOwner, type ContentRefusalCause, type ContentVerbType, type DevtoolsCommand, type DevtoolsContent, type DevtoolsHandle, type DevtoolsVocabulary, type EnumTweak, type ErrorCode, type FileSystemAPI, type FileSystemOptions, type FileSystemResult, type GameLoopHooks, type GameMode, type GameRunHandle, type GameRunOptions, type GeolocationAPI, type GeolocationOptions, type GeolocationResult, type HapticsAPI, type LayoutEntry, type LayoutFile, type LayoutRole, type LayoutRoleMap, type LayoutValues, type LevelPreview, type LevelPreviewCell, type LevelRefusal, type MicrophoneAPI, type MicrophoneRecordOptions, type MicrophoneResult, type MicrophoneStreamOptions, type MotionAttitude, type MotionData, type MotionRotation, type MotionVector, type NormalizedAssetEntry, type NumberTweak, type OrientationData, type PayloadRefusal, type PlayablAssets, type PlayablAudio, type PlayablAudioAutoPauseOptions, type PlayablAudioContext, type PlayablAudioOptions, type PlayablDevice, type PlayablDevtools, PlayablError, type PlayablGame, type PlayablSDK, type PlayablTweaks, type ProgressionNoun, type ProgressionShape, type ReadyResult, type SaveResult, type SceneGrid, type SceneNode, type SceneRect, type SensorsAPI, type StateLevel, type SubmitResult, type TextStyleStamp, type TextTweak, type TweakAppliesOn, type TweakSchema, type TweakSchemaItem, type TweakType, type TweakValue, type TweakValueIssue, type TweakValueRejection, type TweakValues, type TweaksInitOptions, __testing, cellGridHooks, configure, sdk as default };
package/dist/index.js CHANGED
@@ -3,13 +3,20 @@ var LOG_PREFIX = "[playabl/sdk]";
3
3
  var BASE_DOMAIN = "playabl.ai";
4
4
  var MANIFEST_PATH = "/Runtime-Script/sdk/v1/version.json";
5
5
  var ENV_HOST_RE = /\.(dev|staging)\.playabl\.ai$/;
6
- var FALLBACK_RUNTIME_URL = "https://cdn.playabl.ai/Runtime-Script/sdk/v1/runtime.js";
6
+ var CDN_HOSTS = /* @__PURE__ */ new Set([
7
+ "cdn.playabl.ai",
8
+ "cdn-staging.playabl.ai",
9
+ "cdn-dev.playabl.ai"
10
+ ]);
11
+ var FALLBACK_RUNTIME_URL = "https://cdn.playabl.ai/Runtime-Script/sdk/v1/runtime.js?v=sdk-1.1.0-beta.1";
7
12
  function isEnv(value) {
8
13
  return value === "local" || value === "dev" || value === "staging" || value === "prod";
9
14
  }
10
- function detectEnv(hostname = typeof window !== "undefined" ? window.location.hostname : "", search = typeof window !== "undefined" ? window.location.search : "") {
15
+ function forcedEnv(search = typeof window !== "undefined" ? window.location.search : "") {
11
16
  const forced = new URLSearchParams(search).get("env");
12
- if (isEnv(forced)) return forced;
17
+ return isEnv(forced) ? forced : null;
18
+ }
19
+ function envFromHostname(hostname = typeof window !== "undefined" ? window.location.hostname : "") {
13
20
  if (hostname === "localhost" || hostname === "127.0.0.1") return "local";
14
21
  const match = hostname.match(ENV_HOST_RE);
15
22
  return match ? match[1] : "prod";
@@ -18,11 +25,52 @@ function manifestUrlForEnv(env) {
18
25
  const cdnHost = env === "prod" ? "cdn" : `cdn-${env}`;
19
26
  return `https://${cdnHost}.${BASE_DOMAIN}${MANIFEST_PATH}`;
20
27
  }
28
+ function isPlayablCdnUrl(value) {
29
+ let parsed;
30
+ try {
31
+ parsed = new URL(value);
32
+ } catch {
33
+ return false;
34
+ }
35
+ return parsed.protocol === "https:" && parsed.port === "" && CDN_HOSTS.has(parsed.hostname);
36
+ }
37
+ function describe(value) {
38
+ try {
39
+ return typeof value === "string" ? JSON.stringify(value) : `(${typeof value}) ${String(value)}`;
40
+ } catch {
41
+ return `(${typeof value}) (unprintable)`;
42
+ }
43
+ }
44
+ function injectedManifestUrl(source = typeof window !== "undefined" ? window : void 0) {
45
+ if (source === void 0) return void 0;
46
+ let value;
47
+ try {
48
+ value = source.__PLAYABL_MANIFEST_URL__;
49
+ } catch (error) {
50
+ console.warn(`${LOG_PREFIX} could not read window.__PLAYABL_MANIFEST_URL__; ignoring it`, error);
51
+ return void 0;
52
+ }
53
+ if (value === void 0) return void 0;
54
+ if (typeof value === "string" && isPlayablCdnUrl(value)) return value;
55
+ console.warn(
56
+ `${LOG_PREFIX} ignoring window.__PLAYABL_MANIFEST_URL__ ${describe(value)}: not an https URL on cdn.playabl.ai, cdn-staging.playabl.ai or cdn-dev.playabl.ai`
57
+ );
58
+ return void 0;
59
+ }
21
60
  async function resolveRuntimeUrl(options = {}) {
22
61
  if (options.runtimeUrl) return options.runtimeUrl;
23
- const env = detectEnv();
24
- if (!options.manifestUrl && env === "local") return FALLBACK_RUNTIME_URL;
25
- const manifestUrl = options.manifestUrl ?? manifestUrlForEnv(env);
62
+ let manifestUrl = options.manifestUrl;
63
+ if (!manifestUrl) {
64
+ const forced = forcedEnv();
65
+ const injected = forced === null ? injectedManifestUrl() : void 0;
66
+ if (injected) {
67
+ manifestUrl = injected;
68
+ } else {
69
+ const env = forced ?? envFromHostname();
70
+ if (env === "local") return FALLBACK_RUNTIME_URL;
71
+ manifestUrl = options.manifestUrl ?? manifestUrlForEnv(env);
72
+ }
73
+ }
26
74
  try {
27
75
  const response = await fetch(manifestUrl, { cache: "no-store" });
28
76
  if (!response.ok) throw new Error(`manifest HTTP ${response.status}`);
@@ -205,6 +253,29 @@ async function getSDK() {
205
253
  function peekSDK() {
206
254
  return loadedSDK;
207
255
  }
256
+ var layoutGuards = /* @__PURE__ */ new WeakMap();
257
+ function withLayoutMethod(tweaks, options) {
258
+ if (typeof tweaks.layout === "function") return tweaks;
259
+ if (options?.layout !== void 0) {
260
+ console.warn(
261
+ "[Playabl] tweaks.init ignored options.layout: this environment serves a Playabl runtime older than 1.2.0, so tweaks.layout(id) throws NOT_SUPPORTED"
262
+ );
263
+ }
264
+ let guarded = layoutGuards.get(tweaks);
265
+ if (!guarded) {
266
+ guarded = {
267
+ ...tweaks,
268
+ layout: () => {
269
+ throw new PlayablError(
270
+ "NOT_SUPPORTED",
271
+ "tweaks.layout needs Playabl runtime 1.2.0 or newer; this environment serves an older runtime"
272
+ );
273
+ }
274
+ };
275
+ layoutGuards.set(tweaks, guarded);
276
+ }
277
+ return guarded;
278
+ }
208
279
  function requireRuntimeMember(runtime, name) {
209
280
  const member = runtime[name];
210
281
  if (!member) {
@@ -226,7 +297,7 @@ var sdk = {
226
297
  clear: async () => (await getSDK()).gameState.clear()
227
298
  },
228
299
  tweaks: {
229
- init: async (schema, options) => (await getSDK()).tweaks.init(schema, options)
300
+ init: async (schema, options) => withLayoutMethod(await (await getSDK()).tweaks.init(schema, options), options)
230
301
  },
231
302
  assets: {
232
303
  register: async (mapping, options) => (await getSDK()).assets.register(mapping, options)