@plasius/player-system-interface 0.1.0 → 0.1.2

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.
Files changed (8) hide show
  1. package/README.md +33 -0
  2. package/dist/index.cjs +110 -0
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +65 -1
  5. package/dist/index.d.ts +65 -1
  6. package/dist/index.js +103 -0
  7. package/dist/index.js.map +1 -1
  8. package/package.json +8 -8
package/README.md CHANGED
@@ -25,7 +25,10 @@ npm install @plasius/player-system-interface
25
25
  - focus panes and combat-safe reductions
26
26
  - world-space overlay panel definitions
27
27
  - target popup anchors and alert markers
28
+ - overlay accessibility contracts for keyboard, focus restoration, and announcements
29
+ - frame-budget assumptions for diegetic panel updates
28
30
  - Party/System composition metadata
31
+ - portable host-adapter seams and multi-overlay scale expectations
29
32
 
30
33
  It does not own gameplay orchestration or world authority.
31
34
 
@@ -40,6 +43,8 @@ node demo/example.mjs
40
43
 
41
44
  ```ts
42
45
  import {
46
+ createPlayerSystemInterfaceContract,
47
+ createPlayerSystemInterfacePortabilityContract,
43
48
  createWorldSpacePanelDefinition,
44
49
  packageDescriptor,
45
50
  } from "@plasius/player-system-interface";
@@ -52,8 +57,36 @@ const panel = createWorldSpacePanelDefinition({
52
57
  });
53
58
 
54
59
  console.log(packageDescriptor.packageName, panel.pane);
60
+ console.log(createPlayerSystemInterfaceContract().frameBudget.maxFrameMs);
61
+ console.log(
62
+ createPlayerSystemInterfacePortabilityContract().hostAdapters.supportedHosts
63
+ );
55
64
  ```
56
65
 
66
+ ## Interface NFR Contract
67
+
68
+ The inherited feature flag for this work is `isekai.player-system.runtime-nfr.enabled`.
69
+
70
+ `defaultPlayerSystemInterfaceContract` and `createPlayerSystemInterfaceContract()` make these host expectations explicit:
71
+
72
+ - sequential or direct-hotkey keyboard access for overlay activation
73
+ - focus restoration to the trigger, pane heading, or nearest anchor
74
+ - live-region behavior for assistive announcements
75
+ - per-frame interaction budgets for world-space panels
76
+ - partial nested overrides for accessibility and frame-budget values
77
+
78
+ ## Interface Portability Contract
79
+
80
+ The inherited feature flag for this work is `isekai.player-system.runtime-portability.enabled`.
81
+
82
+ `defaultPlayerSystemInterfacePortabilityContract`,
83
+ `createPlayerSystemInterfacePortabilityContract()`, and
84
+ `assessPlayerSystemInterfaceComposition()` make these expectations explicit:
85
+
86
+ - supported overlay hosts stay portable across DOM, native, and snapshot harnesses
87
+ - required adapter capabilities are documented instead of assumed implicitly
88
+ - multi-pane and multi-overlay compositions stay within bounded panel, alert, and focus budgets
89
+
57
90
  ## Governance
58
91
 
59
92
  - ADRs: [docs/adrs](./docs/adrs)
package/dist/index.cjs CHANGED
@@ -24,7 +24,14 @@ __export(index_exports, {
24
24
  PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID: () => PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID,
25
25
  PLAYER_SYSTEM_INTERFACE_PACKAGE: () => PLAYER_SYSTEM_INTERFACE_PACKAGE,
26
26
  PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID: () => PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID,
27
+ PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID: () => PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID,
28
+ PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID: () => PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID,
29
+ assessPlayerSystemInterfaceComposition: () => assessPlayerSystemInterfaceComposition,
30
+ createPlayerSystemInterfaceContract: () => createPlayerSystemInterfaceContract,
31
+ createPlayerSystemInterfacePortabilityContract: () => createPlayerSystemInterfacePortabilityContract,
27
32
  createWorldSpacePanelDefinition: () => createWorldSpacePanelDefinition,
33
+ defaultPlayerSystemInterfaceContract: () => defaultPlayerSystemInterfaceContract,
34
+ defaultPlayerSystemInterfacePortabilityContract: () => defaultPlayerSystemInterfacePortabilityContract,
28
35
  isPlayerSystemInterfaceMode: () => isPlayerSystemInterfaceMode,
29
36
  packageDescriptor: () => packageDescriptor
30
37
  });
@@ -33,25 +40,128 @@ var PLAYER_SYSTEM_INTERFACE_PACKAGE = "@plasius/player-system-interface";
33
40
  var PLAYER_SYSTEM_INTERFACE_ENV_PREFIX = "PLAYER_SYSTEM_INTERFACE";
34
41
  var PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID = "isekai.player-system.packages.enabled";
35
42
  var PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID = PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID;
43
+ var PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID = "isekai.player-system.runtime-nfr.enabled";
44
+ var PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID = "isekai.player-system.runtime-portability.enabled";
36
45
  var packageDescriptor = Object.freeze({
37
46
  packageName: PLAYER_SYSTEM_INTERFACE_PACKAGE,
38
47
  featureFlagId: PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID,
39
48
  envPrefix: PLAYER_SYSTEM_INTERFACE_ENV_PREFIX,
40
49
  summary: "World-space Player System overlays, focus panes, and target-surface contracts for Plasius game experiences."
41
50
  });
51
+ var defaultPlayerSystemInterfaceContract = Object.freeze({
52
+ featureFlagId: PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID,
53
+ accessibility: Object.freeze({
54
+ keyboardPath: "sequential",
55
+ focusRestorationTarget: "trigger",
56
+ liveRegionMode: "polite",
57
+ requiresAccessibleName: true
58
+ }),
59
+ frameBudget: Object.freeze({
60
+ targetFps: 60,
61
+ maxFrameMs: 16,
62
+ maxInteractivePanelsPerFrame: 2
63
+ })
64
+ });
65
+ var defaultPlayerSystemInterfacePortabilityContract = Object.freeze({
66
+ featureFlagId: PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID,
67
+ hostAdapters: Object.freeze({
68
+ supportedHosts: Object.freeze([
69
+ "dom-overlay",
70
+ "native-overlay",
71
+ "headless-snapshot"
72
+ ]),
73
+ requiredCapabilities: Object.freeze([
74
+ "focus-restoration",
75
+ "live-region",
76
+ "anchor-registry"
77
+ ]),
78
+ forbiddenAssumptions: Object.freeze([
79
+ "window-global",
80
+ "single-pane-layout",
81
+ "absolute-scene-coordinates"
82
+ ])
83
+ }),
84
+ compositionScale: Object.freeze({
85
+ maxWorldPanels: 6,
86
+ maxFocusPanes: 3,
87
+ maxAlertMarkers: 8,
88
+ maxInteractivePanelsPerFrame: 2
89
+ })
90
+ });
42
91
  function isPlayerSystemInterfaceMode(value) {
43
92
  return value === "ambient" || value === "focused" || value === "combat-safe";
44
93
  }
45
94
  function createWorldSpacePanelDefinition(input) {
46
95
  return Object.freeze({ ...input });
47
96
  }
97
+ function createPlayerSystemInterfaceContract(input = {}) {
98
+ return Object.freeze({
99
+ featureFlagId: input.featureFlagId ?? defaultPlayerSystemInterfaceContract.featureFlagId,
100
+ accessibility: Object.freeze({
101
+ ...defaultPlayerSystemInterfaceContract.accessibility,
102
+ ...input.accessibility
103
+ }),
104
+ frameBudget: Object.freeze({
105
+ ...defaultPlayerSystemInterfaceContract.frameBudget,
106
+ ...input.frameBudget
107
+ })
108
+ });
109
+ }
110
+ function createPlayerSystemInterfacePortabilityContract(input = {}) {
111
+ return Object.freeze({
112
+ featureFlagId: input.featureFlagId ?? defaultPlayerSystemInterfacePortabilityContract.featureFlagId,
113
+ hostAdapters: Object.freeze({
114
+ ...defaultPlayerSystemInterfacePortabilityContract.hostAdapters,
115
+ ...input.hostAdapters,
116
+ supportedHosts: Object.freeze([
117
+ ...input.hostAdapters?.supportedHosts ?? defaultPlayerSystemInterfacePortabilityContract.hostAdapters.supportedHosts
118
+ ]),
119
+ requiredCapabilities: Object.freeze([
120
+ ...input.hostAdapters?.requiredCapabilities ?? defaultPlayerSystemInterfacePortabilityContract.hostAdapters.requiredCapabilities
121
+ ]),
122
+ forbiddenAssumptions: Object.freeze([
123
+ ...input.hostAdapters?.forbiddenAssumptions ?? defaultPlayerSystemInterfacePortabilityContract.hostAdapters.forbiddenAssumptions
124
+ ])
125
+ }),
126
+ compositionScale: Object.freeze({
127
+ ...defaultPlayerSystemInterfacePortabilityContract.compositionScale,
128
+ ...input.compositionScale
129
+ })
130
+ });
131
+ }
132
+ function assessPlayerSystemInterfaceComposition(sample, contract = defaultPlayerSystemInterfacePortabilityContract) {
133
+ const violations = [];
134
+ if (sample.panelCount > contract.compositionScale.maxWorldPanels) {
135
+ violations.push("panelCount");
136
+ }
137
+ if (sample.focusPaneCount > contract.compositionScale.maxFocusPanes) {
138
+ violations.push("focusPaneCount");
139
+ }
140
+ if (sample.alertMarkerCount > contract.compositionScale.maxAlertMarkers) {
141
+ violations.push("alertMarkerCount");
142
+ }
143
+ if (sample.interactivePanelCount > contract.compositionScale.maxInteractivePanelsPerFrame) {
144
+ violations.push("interactivePanelCount");
145
+ }
146
+ return Object.freeze({
147
+ accepted: violations.length === 0,
148
+ violations: Object.freeze(violations)
149
+ });
150
+ }
48
151
  // Annotate the CommonJS export names for ESM import in node:
49
152
  0 && (module.exports = {
50
153
  PLAYER_SYSTEM_INTERFACE_ENV_PREFIX,
51
154
  PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID,
52
155
  PLAYER_SYSTEM_INTERFACE_PACKAGE,
53
156
  PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID,
157
+ PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID,
158
+ PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID,
159
+ assessPlayerSystemInterfaceComposition,
160
+ createPlayerSystemInterfaceContract,
161
+ createPlayerSystemInterfacePortabilityContract,
54
162
  createWorldSpacePanelDefinition,
163
+ defaultPlayerSystemInterfaceContract,
164
+ defaultPlayerSystemInterfacePortabilityContract,
55
165
  isPlayerSystemInterfaceMode,
56
166
  packageDescriptor
57
167
  });
package/dist/index.cjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface PackageDescriptor {\n readonly packageName: string;\n readonly featureFlagId: string;\n readonly envPrefix: string;\n readonly summary: string;\n}\n\nexport type PlayerSystemInterfaceMode = \"ambient\" | \"focused\" | \"combat-safe\";\n\nexport type PlayerSystemPaneId =\n | \"identity\"\n | \"missions\"\n | \"guild-quests\"\n | \"logs\"\n | \"mcc\"\n | \"tutorial\"\n | \"points-store\";\n\nexport interface WorldSpacePanelDefinition {\n readonly panelId: string;\n readonly pane: PlayerSystemPaneId;\n readonly anchorId: string;\n readonly interactive: boolean;\n}\n\nexport interface OverlayAlertMarker {\n readonly markerId: string;\n readonly severity: \"info\" | \"warning\" | \"danger\";\n readonly anchorId: string;\n}\n\nexport const PLAYER_SYSTEM_INTERFACE_PACKAGE = \"@plasius/player-system-interface\";\nexport const PLAYER_SYSTEM_INTERFACE_ENV_PREFIX = \"PLAYER_SYSTEM_INTERFACE\";\nexport const PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID =\n \"isekai.player-system.packages.enabled\";\nexport const PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID =\n PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID;\n\nexport const packageDescriptor: PackageDescriptor = Object.freeze({\n packageName: PLAYER_SYSTEM_INTERFACE_PACKAGE,\n featureFlagId: PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID,\n envPrefix: PLAYER_SYSTEM_INTERFACE_ENV_PREFIX,\n summary:\n \"World-space Player System overlays, focus panes, and target-surface contracts for Plasius game experiences.\",\n});\n\nexport function isPlayerSystemInterfaceMode(\n value: string\n): value is PlayerSystemInterfaceMode {\n return value === \"ambient\" || value === \"focused\" || value === \"combat-safe\";\n}\n\nexport function createWorldSpacePanelDefinition(\n input: WorldSpacePanelDefinition\n): WorldSpacePanelDefinition {\n return Object.freeze({ ...input });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA+BO,IAAM,kCAAkC;AACxC,IAAM,qCAAqC;AAC3C,IAAM,yCACX;AACK,IAAM,0CACX;AAEK,IAAM,oBAAuC,OAAO,OAAO;AAAA,EAChE,aAAa;AAAA,EACb,eAAe;AAAA,EACf,WAAW;AAAA,EACX,SACE;AACJ,CAAC;AAEM,SAAS,4BACd,OACoC;AACpC,SAAO,UAAU,aAAa,UAAU,aAAa,UAAU;AACjE;AAEO,SAAS,gCACd,OAC2B;AAC3B,SAAO,OAAO,OAAO,EAAE,GAAG,MAAM,CAAC;AACnC;","names":[]}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface PackageDescriptor {\n readonly packageName: string;\n readonly featureFlagId: string;\n readonly envPrefix: string;\n readonly summary: string;\n}\n\nexport type OverlayKeyboardPath = \"sequential\" | \"direct-hotkey\" | \"read-only\";\n\nexport interface OverlayAccessibilityContract {\n readonly keyboardPath: OverlayKeyboardPath;\n readonly focusRestorationTarget: \"trigger\" | \"pane-heading\" | \"nearest-anchor\";\n readonly liveRegionMode: \"polite\" | \"assertive\" | \"off\";\n readonly requiresAccessibleName: boolean;\n}\n\nexport interface InterfaceFrameBudget {\n readonly targetFps: number;\n readonly maxFrameMs: number;\n readonly maxInteractivePanelsPerFrame: number;\n}\n\nexport type OverlayHostKind =\n | \"dom-overlay\"\n | \"native-overlay\"\n | \"headless-snapshot\";\n\nexport type OverlayAdapterCapability =\n | \"focus-restoration\"\n | \"live-region\"\n | \"anchor-registry\";\n\nexport interface OverlayHostAdapterContract {\n readonly supportedHosts: readonly OverlayHostKind[];\n readonly requiredCapabilities: readonly OverlayAdapterCapability[];\n readonly forbiddenAssumptions: readonly string[];\n}\n\nexport interface OverlayCompositionScaleContract {\n readonly maxWorldPanels: number;\n readonly maxFocusPanes: number;\n readonly maxAlertMarkers: number;\n readonly maxInteractivePanelsPerFrame: number;\n}\n\nexport interface PlayerSystemInterfaceContract {\n readonly featureFlagId: string;\n readonly accessibility: OverlayAccessibilityContract;\n readonly frameBudget: InterfaceFrameBudget;\n}\n\nexport interface PlayerSystemInterfacePortabilityContract {\n readonly featureFlagId: string;\n readonly hostAdapters: OverlayHostAdapterContract;\n readonly compositionScale: OverlayCompositionScaleContract;\n}\n\nexport interface PlayerSystemInterfaceContractInput {\n readonly featureFlagId?: string;\n readonly accessibility?: Partial<OverlayAccessibilityContract>;\n readonly frameBudget?: Partial<InterfaceFrameBudget>;\n}\n\nexport interface PlayerSystemInterfacePortabilityContractInput {\n readonly featureFlagId?: string;\n readonly hostAdapters?: Partial<OverlayHostAdapterContract>;\n readonly compositionScale?: Partial<OverlayCompositionScaleContract>;\n}\n\nexport type PlayerSystemInterfaceMode = \"ambient\" | \"focused\" | \"combat-safe\";\n\nexport type PlayerSystemPaneId =\n | \"identity\"\n | \"missions\"\n | \"guild-quests\"\n | \"logs\"\n | \"mcc\"\n | \"tutorial\"\n | \"points-store\";\n\nexport interface WorldSpacePanelDefinition {\n readonly panelId: string;\n readonly pane: PlayerSystemPaneId;\n readonly anchorId: string;\n readonly interactive: boolean;\n readonly accessibilityLabel?: string;\n readonly focusOrder?: number;\n}\n\nexport interface OverlayAlertMarker {\n readonly markerId: string;\n readonly severity: \"info\" | \"warning\" | \"danger\";\n readonly anchorId: string;\n}\n\nexport interface WorldSpaceCompositionSample {\n readonly panelCount: number;\n readonly focusPaneCount: number;\n readonly alertMarkerCount: number;\n readonly interactivePanelCount: number;\n}\n\nexport interface InterfaceContractAssessment {\n readonly accepted: boolean;\n readonly violations: readonly string[];\n}\n\nexport const PLAYER_SYSTEM_INTERFACE_PACKAGE = \"@plasius/player-system-interface\";\nexport const PLAYER_SYSTEM_INTERFACE_ENV_PREFIX = \"PLAYER_SYSTEM_INTERFACE\";\nexport const PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID =\n \"isekai.player-system.packages.enabled\";\nexport const PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID =\n PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID;\nexport const PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID =\n \"isekai.player-system.runtime-nfr.enabled\";\nexport const PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID =\n \"isekai.player-system.runtime-portability.enabled\";\n\nexport const packageDescriptor: PackageDescriptor = Object.freeze({\n packageName: PLAYER_SYSTEM_INTERFACE_PACKAGE,\n featureFlagId: PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID,\n envPrefix: PLAYER_SYSTEM_INTERFACE_ENV_PREFIX,\n summary:\n \"World-space Player System overlays, focus panes, and target-surface contracts for Plasius game experiences.\",\n});\n\nexport const defaultPlayerSystemInterfaceContract: PlayerSystemInterfaceContract =\n Object.freeze({\n featureFlagId: PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID,\n accessibility: Object.freeze({\n keyboardPath: \"sequential\",\n focusRestorationTarget: \"trigger\",\n liveRegionMode: \"polite\",\n requiresAccessibleName: true,\n }),\n frameBudget: Object.freeze({\n targetFps: 60,\n maxFrameMs: 16,\n maxInteractivePanelsPerFrame: 2,\n }),\n });\n\nexport const defaultPlayerSystemInterfacePortabilityContract: PlayerSystemInterfacePortabilityContract =\n Object.freeze({\n featureFlagId: PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID,\n hostAdapters: Object.freeze({\n supportedHosts: Object.freeze([\n \"dom-overlay\",\n \"native-overlay\",\n \"headless-snapshot\",\n ] satisfies OverlayHostKind[]),\n requiredCapabilities: Object.freeze([\n \"focus-restoration\",\n \"live-region\",\n \"anchor-registry\",\n ] satisfies OverlayAdapterCapability[]),\n forbiddenAssumptions: Object.freeze([\n \"window-global\",\n \"single-pane-layout\",\n \"absolute-scene-coordinates\",\n ]),\n }),\n compositionScale: Object.freeze({\n maxWorldPanels: 6,\n maxFocusPanes: 3,\n maxAlertMarkers: 8,\n maxInteractivePanelsPerFrame: 2,\n }),\n });\n\nexport function isPlayerSystemInterfaceMode(\n value: string\n): value is PlayerSystemInterfaceMode {\n return value === \"ambient\" || value === \"focused\" || value === \"combat-safe\";\n}\n\nexport function createWorldSpacePanelDefinition(\n input: WorldSpacePanelDefinition\n): WorldSpacePanelDefinition {\n return Object.freeze({ ...input });\n}\n\nexport function createPlayerSystemInterfaceContract(\n input: PlayerSystemInterfaceContractInput = {}\n): PlayerSystemInterfaceContract {\n return Object.freeze({\n featureFlagId:\n input.featureFlagId ?? defaultPlayerSystemInterfaceContract.featureFlagId,\n accessibility: Object.freeze({\n ...defaultPlayerSystemInterfaceContract.accessibility,\n ...input.accessibility,\n }),\n frameBudget: Object.freeze({\n ...defaultPlayerSystemInterfaceContract.frameBudget,\n ...input.frameBudget,\n }),\n });\n}\n\nexport function createPlayerSystemInterfacePortabilityContract(\n input: PlayerSystemInterfacePortabilityContractInput = {}\n): PlayerSystemInterfacePortabilityContract {\n return Object.freeze({\n featureFlagId:\n input.featureFlagId ??\n defaultPlayerSystemInterfacePortabilityContract.featureFlagId,\n hostAdapters: Object.freeze({\n ...defaultPlayerSystemInterfacePortabilityContract.hostAdapters,\n ...input.hostAdapters,\n supportedHosts: Object.freeze([\n ...(input.hostAdapters?.supportedHosts ??\n defaultPlayerSystemInterfacePortabilityContract.hostAdapters\n .supportedHosts),\n ]),\n requiredCapabilities: Object.freeze([\n ...(input.hostAdapters?.requiredCapabilities ??\n defaultPlayerSystemInterfacePortabilityContract.hostAdapters\n .requiredCapabilities),\n ]),\n forbiddenAssumptions: Object.freeze([\n ...(input.hostAdapters?.forbiddenAssumptions ??\n defaultPlayerSystemInterfacePortabilityContract.hostAdapters\n .forbiddenAssumptions),\n ]),\n }),\n compositionScale: Object.freeze({\n ...defaultPlayerSystemInterfacePortabilityContract.compositionScale,\n ...input.compositionScale,\n }),\n });\n}\n\nexport function assessPlayerSystemInterfaceComposition(\n sample: WorldSpaceCompositionSample,\n contract: PlayerSystemInterfacePortabilityContract = defaultPlayerSystemInterfacePortabilityContract\n): InterfaceContractAssessment {\n const violations: string[] = [];\n\n if (sample.panelCount > contract.compositionScale.maxWorldPanels) {\n violations.push(\"panelCount\");\n }\n\n if (sample.focusPaneCount > contract.compositionScale.maxFocusPanes) {\n violations.push(\"focusPaneCount\");\n }\n\n if (sample.alertMarkerCount > contract.compositionScale.maxAlertMarkers) {\n violations.push(\"alertMarkerCount\");\n }\n\n if (\n sample.interactivePanelCount >\n contract.compositionScale.maxInteractivePanelsPerFrame\n ) {\n violations.push(\"interactivePanelCount\");\n }\n\n return Object.freeze({\n accepted: violations.length === 0,\n violations: Object.freeze(violations),\n });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA2GO,IAAM,kCAAkC;AACxC,IAAM,qCAAqC;AAC3C,IAAM,yCACX;AACK,IAAM,0CACX;AACK,IAAM,4CACX;AACK,IAAM,oDACX;AAEK,IAAM,oBAAuC,OAAO,OAAO;AAAA,EAChE,aAAa;AAAA,EACb,eAAe;AAAA,EACf,WAAW;AAAA,EACX,SACE;AACJ,CAAC;AAEM,IAAM,uCACX,OAAO,OAAO;AAAA,EACZ,eAAe;AAAA,EACf,eAAe,OAAO,OAAO;AAAA,IAC3B,cAAc;AAAA,IACd,wBAAwB;AAAA,IACxB,gBAAgB;AAAA,IAChB,wBAAwB;AAAA,EAC1B,CAAC;AAAA,EACD,aAAa,OAAO,OAAO;AAAA,IACzB,WAAW;AAAA,IACX,YAAY;AAAA,IACZ,8BAA8B;AAAA,EAChC,CAAC;AACH,CAAC;AAEI,IAAM,kDACX,OAAO,OAAO;AAAA,EACZ,eAAe;AAAA,EACf,cAAc,OAAO,OAAO;AAAA,IAC1B,gBAAgB,OAAO,OAAO;AAAA,MAC5B;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAA6B;AAAA,IAC7B,sBAAsB,OAAO,OAAO;AAAA,MAClC;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAsC;AAAA,IACtC,sBAAsB,OAAO,OAAO;AAAA,MAClC;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AAAA,EACD,kBAAkB,OAAO,OAAO;AAAA,IAC9B,gBAAgB;AAAA,IAChB,eAAe;AAAA,IACf,iBAAiB;AAAA,IACjB,8BAA8B;AAAA,EAChC,CAAC;AACH,CAAC;AAEI,SAAS,4BACd,OACoC;AACpC,SAAO,UAAU,aAAa,UAAU,aAAa,UAAU;AACjE;AAEO,SAAS,gCACd,OAC2B;AAC3B,SAAO,OAAO,OAAO,EAAE,GAAG,MAAM,CAAC;AACnC;AAEO,SAAS,oCACd,QAA4C,CAAC,GACd;AAC/B,SAAO,OAAO,OAAO;AAAA,IACnB,eACE,MAAM,iBAAiB,qCAAqC;AAAA,IAC9D,eAAe,OAAO,OAAO;AAAA,MAC3B,GAAG,qCAAqC;AAAA,MACxC,GAAG,MAAM;AAAA,IACX,CAAC;AAAA,IACD,aAAa,OAAO,OAAO;AAAA,MACzB,GAAG,qCAAqC;AAAA,MACxC,GAAG,MAAM;AAAA,IACX,CAAC;AAAA,EACH,CAAC;AACH;AAEO,SAAS,+CACd,QAAuD,CAAC,GACd;AAC1C,SAAO,OAAO,OAAO;AAAA,IACnB,eACE,MAAM,iBACN,gDAAgD;AAAA,IAClD,cAAc,OAAO,OAAO;AAAA,MAC1B,GAAG,gDAAgD;AAAA,MACnD,GAAG,MAAM;AAAA,MACT,gBAAgB,OAAO,OAAO;AAAA,QAC5B,GAAI,MAAM,cAAc,kBACtB,gDAAgD,aAC7C;AAAA,MACP,CAAC;AAAA,MACD,sBAAsB,OAAO,OAAO;AAAA,QAClC,GAAI,MAAM,cAAc,wBACtB,gDAAgD,aAC7C;AAAA,MACP,CAAC;AAAA,MACD,sBAAsB,OAAO,OAAO;AAAA,QAClC,GAAI,MAAM,cAAc,wBACtB,gDAAgD,aAC7C;AAAA,MACP,CAAC;AAAA,IACH,CAAC;AAAA,IACD,kBAAkB,OAAO,OAAO;AAAA,MAC9B,GAAG,gDAAgD;AAAA,MACnD,GAAG,MAAM;AAAA,IACX,CAAC;AAAA,EACH,CAAC;AACH;AAEO,SAAS,uCACd,QACA,WAAqD,iDACxB;AAC7B,QAAM,aAAuB,CAAC;AAE9B,MAAI,OAAO,aAAa,SAAS,iBAAiB,gBAAgB;AAChE,eAAW,KAAK,YAAY;AAAA,EAC9B;AAEA,MAAI,OAAO,iBAAiB,SAAS,iBAAiB,eAAe;AACnE,eAAW,KAAK,gBAAgB;AAAA,EAClC;AAEA,MAAI,OAAO,mBAAmB,SAAS,iBAAiB,iBAAiB;AACvE,eAAW,KAAK,kBAAkB;AAAA,EACpC;AAEA,MACE,OAAO,wBACP,SAAS,iBAAiB,8BAC1B;AACA,eAAW,KAAK,uBAAuB;AAAA,EACzC;AAEA,SAAO,OAAO,OAAO;AAAA,IACnB,UAAU,WAAW,WAAW;AAAA,IAChC,YAAY,OAAO,OAAO,UAAU;AAAA,EACtC,CAAC;AACH;","names":[]}
package/dist/index.d.cts CHANGED
@@ -4,6 +4,51 @@ interface PackageDescriptor {
4
4
  readonly envPrefix: string;
5
5
  readonly summary: string;
6
6
  }
7
+ type OverlayKeyboardPath = "sequential" | "direct-hotkey" | "read-only";
8
+ interface OverlayAccessibilityContract {
9
+ readonly keyboardPath: OverlayKeyboardPath;
10
+ readonly focusRestorationTarget: "trigger" | "pane-heading" | "nearest-anchor";
11
+ readonly liveRegionMode: "polite" | "assertive" | "off";
12
+ readonly requiresAccessibleName: boolean;
13
+ }
14
+ interface InterfaceFrameBudget {
15
+ readonly targetFps: number;
16
+ readonly maxFrameMs: number;
17
+ readonly maxInteractivePanelsPerFrame: number;
18
+ }
19
+ type OverlayHostKind = "dom-overlay" | "native-overlay" | "headless-snapshot";
20
+ type OverlayAdapterCapability = "focus-restoration" | "live-region" | "anchor-registry";
21
+ interface OverlayHostAdapterContract {
22
+ readonly supportedHosts: readonly OverlayHostKind[];
23
+ readonly requiredCapabilities: readonly OverlayAdapterCapability[];
24
+ readonly forbiddenAssumptions: readonly string[];
25
+ }
26
+ interface OverlayCompositionScaleContract {
27
+ readonly maxWorldPanels: number;
28
+ readonly maxFocusPanes: number;
29
+ readonly maxAlertMarkers: number;
30
+ readonly maxInteractivePanelsPerFrame: number;
31
+ }
32
+ interface PlayerSystemInterfaceContract {
33
+ readonly featureFlagId: string;
34
+ readonly accessibility: OverlayAccessibilityContract;
35
+ readonly frameBudget: InterfaceFrameBudget;
36
+ }
37
+ interface PlayerSystemInterfacePortabilityContract {
38
+ readonly featureFlagId: string;
39
+ readonly hostAdapters: OverlayHostAdapterContract;
40
+ readonly compositionScale: OverlayCompositionScaleContract;
41
+ }
42
+ interface PlayerSystemInterfaceContractInput {
43
+ readonly featureFlagId?: string;
44
+ readonly accessibility?: Partial<OverlayAccessibilityContract>;
45
+ readonly frameBudget?: Partial<InterfaceFrameBudget>;
46
+ }
47
+ interface PlayerSystemInterfacePortabilityContractInput {
48
+ readonly featureFlagId?: string;
49
+ readonly hostAdapters?: Partial<OverlayHostAdapterContract>;
50
+ readonly compositionScale?: Partial<OverlayCompositionScaleContract>;
51
+ }
7
52
  type PlayerSystemInterfaceMode = "ambient" | "focused" | "combat-safe";
8
53
  type PlayerSystemPaneId = "identity" | "missions" | "guild-quests" | "logs" | "mcc" | "tutorial" | "points-store";
9
54
  interface WorldSpacePanelDefinition {
@@ -11,18 +56,37 @@ interface WorldSpacePanelDefinition {
11
56
  readonly pane: PlayerSystemPaneId;
12
57
  readonly anchorId: string;
13
58
  readonly interactive: boolean;
59
+ readonly accessibilityLabel?: string;
60
+ readonly focusOrder?: number;
14
61
  }
15
62
  interface OverlayAlertMarker {
16
63
  readonly markerId: string;
17
64
  readonly severity: "info" | "warning" | "danger";
18
65
  readonly anchorId: string;
19
66
  }
67
+ interface WorldSpaceCompositionSample {
68
+ readonly panelCount: number;
69
+ readonly focusPaneCount: number;
70
+ readonly alertMarkerCount: number;
71
+ readonly interactivePanelCount: number;
72
+ }
73
+ interface InterfaceContractAssessment {
74
+ readonly accepted: boolean;
75
+ readonly violations: readonly string[];
76
+ }
20
77
  declare const PLAYER_SYSTEM_INTERFACE_PACKAGE = "@plasius/player-system-interface";
21
78
  declare const PLAYER_SYSTEM_INTERFACE_ENV_PREFIX = "PLAYER_SYSTEM_INTERFACE";
22
79
  declare const PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID = "isekai.player-system.packages.enabled";
23
80
  declare const PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID = "isekai.player-system.packages.enabled";
81
+ declare const PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID = "isekai.player-system.runtime-nfr.enabled";
82
+ declare const PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID = "isekai.player-system.runtime-portability.enabled";
24
83
  declare const packageDescriptor: PackageDescriptor;
84
+ declare const defaultPlayerSystemInterfaceContract: PlayerSystemInterfaceContract;
85
+ declare const defaultPlayerSystemInterfacePortabilityContract: PlayerSystemInterfacePortabilityContract;
25
86
  declare function isPlayerSystemInterfaceMode(value: string): value is PlayerSystemInterfaceMode;
26
87
  declare function createWorldSpacePanelDefinition(input: WorldSpacePanelDefinition): WorldSpacePanelDefinition;
88
+ declare function createPlayerSystemInterfaceContract(input?: PlayerSystemInterfaceContractInput): PlayerSystemInterfaceContract;
89
+ declare function createPlayerSystemInterfacePortabilityContract(input?: PlayerSystemInterfacePortabilityContractInput): PlayerSystemInterfacePortabilityContract;
90
+ declare function assessPlayerSystemInterfaceComposition(sample: WorldSpaceCompositionSample, contract?: PlayerSystemInterfacePortabilityContract): InterfaceContractAssessment;
27
91
 
28
- export { type OverlayAlertMarker, PLAYER_SYSTEM_INTERFACE_ENV_PREFIX, PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID, PLAYER_SYSTEM_INTERFACE_PACKAGE, PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID, type PackageDescriptor, type PlayerSystemInterfaceMode, type PlayerSystemPaneId, type WorldSpacePanelDefinition, createWorldSpacePanelDefinition, isPlayerSystemInterfaceMode, packageDescriptor };
92
+ export { type InterfaceContractAssessment, type InterfaceFrameBudget, type OverlayAccessibilityContract, type OverlayAdapterCapability, type OverlayAlertMarker, type OverlayCompositionScaleContract, type OverlayHostAdapterContract, type OverlayHostKind, type OverlayKeyboardPath, PLAYER_SYSTEM_INTERFACE_ENV_PREFIX, PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID, PLAYER_SYSTEM_INTERFACE_PACKAGE, PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID, PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID, PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID, type PackageDescriptor, type PlayerSystemInterfaceContract, type PlayerSystemInterfaceContractInput, type PlayerSystemInterfaceMode, type PlayerSystemInterfacePortabilityContract, type PlayerSystemInterfacePortabilityContractInput, type PlayerSystemPaneId, type WorldSpaceCompositionSample, type WorldSpacePanelDefinition, assessPlayerSystemInterfaceComposition, createPlayerSystemInterfaceContract, createPlayerSystemInterfacePortabilityContract, createWorldSpacePanelDefinition, defaultPlayerSystemInterfaceContract, defaultPlayerSystemInterfacePortabilityContract, isPlayerSystemInterfaceMode, packageDescriptor };
package/dist/index.d.ts CHANGED
@@ -4,6 +4,51 @@ interface PackageDescriptor {
4
4
  readonly envPrefix: string;
5
5
  readonly summary: string;
6
6
  }
7
+ type OverlayKeyboardPath = "sequential" | "direct-hotkey" | "read-only";
8
+ interface OverlayAccessibilityContract {
9
+ readonly keyboardPath: OverlayKeyboardPath;
10
+ readonly focusRestorationTarget: "trigger" | "pane-heading" | "nearest-anchor";
11
+ readonly liveRegionMode: "polite" | "assertive" | "off";
12
+ readonly requiresAccessibleName: boolean;
13
+ }
14
+ interface InterfaceFrameBudget {
15
+ readonly targetFps: number;
16
+ readonly maxFrameMs: number;
17
+ readonly maxInteractivePanelsPerFrame: number;
18
+ }
19
+ type OverlayHostKind = "dom-overlay" | "native-overlay" | "headless-snapshot";
20
+ type OverlayAdapterCapability = "focus-restoration" | "live-region" | "anchor-registry";
21
+ interface OverlayHostAdapterContract {
22
+ readonly supportedHosts: readonly OverlayHostKind[];
23
+ readonly requiredCapabilities: readonly OverlayAdapterCapability[];
24
+ readonly forbiddenAssumptions: readonly string[];
25
+ }
26
+ interface OverlayCompositionScaleContract {
27
+ readonly maxWorldPanels: number;
28
+ readonly maxFocusPanes: number;
29
+ readonly maxAlertMarkers: number;
30
+ readonly maxInteractivePanelsPerFrame: number;
31
+ }
32
+ interface PlayerSystemInterfaceContract {
33
+ readonly featureFlagId: string;
34
+ readonly accessibility: OverlayAccessibilityContract;
35
+ readonly frameBudget: InterfaceFrameBudget;
36
+ }
37
+ interface PlayerSystemInterfacePortabilityContract {
38
+ readonly featureFlagId: string;
39
+ readonly hostAdapters: OverlayHostAdapterContract;
40
+ readonly compositionScale: OverlayCompositionScaleContract;
41
+ }
42
+ interface PlayerSystemInterfaceContractInput {
43
+ readonly featureFlagId?: string;
44
+ readonly accessibility?: Partial<OverlayAccessibilityContract>;
45
+ readonly frameBudget?: Partial<InterfaceFrameBudget>;
46
+ }
47
+ interface PlayerSystemInterfacePortabilityContractInput {
48
+ readonly featureFlagId?: string;
49
+ readonly hostAdapters?: Partial<OverlayHostAdapterContract>;
50
+ readonly compositionScale?: Partial<OverlayCompositionScaleContract>;
51
+ }
7
52
  type PlayerSystemInterfaceMode = "ambient" | "focused" | "combat-safe";
8
53
  type PlayerSystemPaneId = "identity" | "missions" | "guild-quests" | "logs" | "mcc" | "tutorial" | "points-store";
9
54
  interface WorldSpacePanelDefinition {
@@ -11,18 +56,37 @@ interface WorldSpacePanelDefinition {
11
56
  readonly pane: PlayerSystemPaneId;
12
57
  readonly anchorId: string;
13
58
  readonly interactive: boolean;
59
+ readonly accessibilityLabel?: string;
60
+ readonly focusOrder?: number;
14
61
  }
15
62
  interface OverlayAlertMarker {
16
63
  readonly markerId: string;
17
64
  readonly severity: "info" | "warning" | "danger";
18
65
  readonly anchorId: string;
19
66
  }
67
+ interface WorldSpaceCompositionSample {
68
+ readonly panelCount: number;
69
+ readonly focusPaneCount: number;
70
+ readonly alertMarkerCount: number;
71
+ readonly interactivePanelCount: number;
72
+ }
73
+ interface InterfaceContractAssessment {
74
+ readonly accepted: boolean;
75
+ readonly violations: readonly string[];
76
+ }
20
77
  declare const PLAYER_SYSTEM_INTERFACE_PACKAGE = "@plasius/player-system-interface";
21
78
  declare const PLAYER_SYSTEM_INTERFACE_ENV_PREFIX = "PLAYER_SYSTEM_INTERFACE";
22
79
  declare const PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID = "isekai.player-system.packages.enabled";
23
80
  declare const PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID = "isekai.player-system.packages.enabled";
81
+ declare const PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID = "isekai.player-system.runtime-nfr.enabled";
82
+ declare const PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID = "isekai.player-system.runtime-portability.enabled";
24
83
  declare const packageDescriptor: PackageDescriptor;
84
+ declare const defaultPlayerSystemInterfaceContract: PlayerSystemInterfaceContract;
85
+ declare const defaultPlayerSystemInterfacePortabilityContract: PlayerSystemInterfacePortabilityContract;
25
86
  declare function isPlayerSystemInterfaceMode(value: string): value is PlayerSystemInterfaceMode;
26
87
  declare function createWorldSpacePanelDefinition(input: WorldSpacePanelDefinition): WorldSpacePanelDefinition;
88
+ declare function createPlayerSystemInterfaceContract(input?: PlayerSystemInterfaceContractInput): PlayerSystemInterfaceContract;
89
+ declare function createPlayerSystemInterfacePortabilityContract(input?: PlayerSystemInterfacePortabilityContractInput): PlayerSystemInterfacePortabilityContract;
90
+ declare function assessPlayerSystemInterfaceComposition(sample: WorldSpaceCompositionSample, contract?: PlayerSystemInterfacePortabilityContract): InterfaceContractAssessment;
27
91
 
28
- export { type OverlayAlertMarker, PLAYER_SYSTEM_INTERFACE_ENV_PREFIX, PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID, PLAYER_SYSTEM_INTERFACE_PACKAGE, PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID, type PackageDescriptor, type PlayerSystemInterfaceMode, type PlayerSystemPaneId, type WorldSpacePanelDefinition, createWorldSpacePanelDefinition, isPlayerSystemInterfaceMode, packageDescriptor };
92
+ export { type InterfaceContractAssessment, type InterfaceFrameBudget, type OverlayAccessibilityContract, type OverlayAdapterCapability, type OverlayAlertMarker, type OverlayCompositionScaleContract, type OverlayHostAdapterContract, type OverlayHostKind, type OverlayKeyboardPath, PLAYER_SYSTEM_INTERFACE_ENV_PREFIX, PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID, PLAYER_SYSTEM_INTERFACE_PACKAGE, PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID, PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID, PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID, type PackageDescriptor, type PlayerSystemInterfaceContract, type PlayerSystemInterfaceContractInput, type PlayerSystemInterfaceMode, type PlayerSystemInterfacePortabilityContract, type PlayerSystemInterfacePortabilityContractInput, type PlayerSystemPaneId, type WorldSpaceCompositionSample, type WorldSpacePanelDefinition, assessPlayerSystemInterfaceComposition, createPlayerSystemInterfaceContract, createPlayerSystemInterfacePortabilityContract, createWorldSpacePanelDefinition, defaultPlayerSystemInterfaceContract, defaultPlayerSystemInterfacePortabilityContract, isPlayerSystemInterfaceMode, packageDescriptor };
package/dist/index.js CHANGED
@@ -3,24 +3,127 @@ var PLAYER_SYSTEM_INTERFACE_PACKAGE = "@plasius/player-system-interface";
3
3
  var PLAYER_SYSTEM_INTERFACE_ENV_PREFIX = "PLAYER_SYSTEM_INTERFACE";
4
4
  var PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID = "isekai.player-system.packages.enabled";
5
5
  var PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID = PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID;
6
+ var PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID = "isekai.player-system.runtime-nfr.enabled";
7
+ var PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID = "isekai.player-system.runtime-portability.enabled";
6
8
  var packageDescriptor = Object.freeze({
7
9
  packageName: PLAYER_SYSTEM_INTERFACE_PACKAGE,
8
10
  featureFlagId: PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID,
9
11
  envPrefix: PLAYER_SYSTEM_INTERFACE_ENV_PREFIX,
10
12
  summary: "World-space Player System overlays, focus panes, and target-surface contracts for Plasius game experiences."
11
13
  });
14
+ var defaultPlayerSystemInterfaceContract = Object.freeze({
15
+ featureFlagId: PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID,
16
+ accessibility: Object.freeze({
17
+ keyboardPath: "sequential",
18
+ focusRestorationTarget: "trigger",
19
+ liveRegionMode: "polite",
20
+ requiresAccessibleName: true
21
+ }),
22
+ frameBudget: Object.freeze({
23
+ targetFps: 60,
24
+ maxFrameMs: 16,
25
+ maxInteractivePanelsPerFrame: 2
26
+ })
27
+ });
28
+ var defaultPlayerSystemInterfacePortabilityContract = Object.freeze({
29
+ featureFlagId: PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID,
30
+ hostAdapters: Object.freeze({
31
+ supportedHosts: Object.freeze([
32
+ "dom-overlay",
33
+ "native-overlay",
34
+ "headless-snapshot"
35
+ ]),
36
+ requiredCapabilities: Object.freeze([
37
+ "focus-restoration",
38
+ "live-region",
39
+ "anchor-registry"
40
+ ]),
41
+ forbiddenAssumptions: Object.freeze([
42
+ "window-global",
43
+ "single-pane-layout",
44
+ "absolute-scene-coordinates"
45
+ ])
46
+ }),
47
+ compositionScale: Object.freeze({
48
+ maxWorldPanels: 6,
49
+ maxFocusPanes: 3,
50
+ maxAlertMarkers: 8,
51
+ maxInteractivePanelsPerFrame: 2
52
+ })
53
+ });
12
54
  function isPlayerSystemInterfaceMode(value) {
13
55
  return value === "ambient" || value === "focused" || value === "combat-safe";
14
56
  }
15
57
  function createWorldSpacePanelDefinition(input) {
16
58
  return Object.freeze({ ...input });
17
59
  }
60
+ function createPlayerSystemInterfaceContract(input = {}) {
61
+ return Object.freeze({
62
+ featureFlagId: input.featureFlagId ?? defaultPlayerSystemInterfaceContract.featureFlagId,
63
+ accessibility: Object.freeze({
64
+ ...defaultPlayerSystemInterfaceContract.accessibility,
65
+ ...input.accessibility
66
+ }),
67
+ frameBudget: Object.freeze({
68
+ ...defaultPlayerSystemInterfaceContract.frameBudget,
69
+ ...input.frameBudget
70
+ })
71
+ });
72
+ }
73
+ function createPlayerSystemInterfacePortabilityContract(input = {}) {
74
+ return Object.freeze({
75
+ featureFlagId: input.featureFlagId ?? defaultPlayerSystemInterfacePortabilityContract.featureFlagId,
76
+ hostAdapters: Object.freeze({
77
+ ...defaultPlayerSystemInterfacePortabilityContract.hostAdapters,
78
+ ...input.hostAdapters,
79
+ supportedHosts: Object.freeze([
80
+ ...input.hostAdapters?.supportedHosts ?? defaultPlayerSystemInterfacePortabilityContract.hostAdapters.supportedHosts
81
+ ]),
82
+ requiredCapabilities: Object.freeze([
83
+ ...input.hostAdapters?.requiredCapabilities ?? defaultPlayerSystemInterfacePortabilityContract.hostAdapters.requiredCapabilities
84
+ ]),
85
+ forbiddenAssumptions: Object.freeze([
86
+ ...input.hostAdapters?.forbiddenAssumptions ?? defaultPlayerSystemInterfacePortabilityContract.hostAdapters.forbiddenAssumptions
87
+ ])
88
+ }),
89
+ compositionScale: Object.freeze({
90
+ ...defaultPlayerSystemInterfacePortabilityContract.compositionScale,
91
+ ...input.compositionScale
92
+ })
93
+ });
94
+ }
95
+ function assessPlayerSystemInterfaceComposition(sample, contract = defaultPlayerSystemInterfacePortabilityContract) {
96
+ const violations = [];
97
+ if (sample.panelCount > contract.compositionScale.maxWorldPanels) {
98
+ violations.push("panelCount");
99
+ }
100
+ if (sample.focusPaneCount > contract.compositionScale.maxFocusPanes) {
101
+ violations.push("focusPaneCount");
102
+ }
103
+ if (sample.alertMarkerCount > contract.compositionScale.maxAlertMarkers) {
104
+ violations.push("alertMarkerCount");
105
+ }
106
+ if (sample.interactivePanelCount > contract.compositionScale.maxInteractivePanelsPerFrame) {
107
+ violations.push("interactivePanelCount");
108
+ }
109
+ return Object.freeze({
110
+ accepted: violations.length === 0,
111
+ violations: Object.freeze(violations)
112
+ });
113
+ }
18
114
  export {
19
115
  PLAYER_SYSTEM_INTERFACE_ENV_PREFIX,
20
116
  PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID,
21
117
  PLAYER_SYSTEM_INTERFACE_PACKAGE,
22
118
  PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID,
119
+ PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID,
120
+ PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID,
121
+ assessPlayerSystemInterfaceComposition,
122
+ createPlayerSystemInterfaceContract,
123
+ createPlayerSystemInterfacePortabilityContract,
23
124
  createWorldSpacePanelDefinition,
125
+ defaultPlayerSystemInterfaceContract,
126
+ defaultPlayerSystemInterfacePortabilityContract,
24
127
  isPlayerSystemInterfaceMode,
25
128
  packageDescriptor
26
129
  };
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface PackageDescriptor {\n readonly packageName: string;\n readonly featureFlagId: string;\n readonly envPrefix: string;\n readonly summary: string;\n}\n\nexport type PlayerSystemInterfaceMode = \"ambient\" | \"focused\" | \"combat-safe\";\n\nexport type PlayerSystemPaneId =\n | \"identity\"\n | \"missions\"\n | \"guild-quests\"\n | \"logs\"\n | \"mcc\"\n | \"tutorial\"\n | \"points-store\";\n\nexport interface WorldSpacePanelDefinition {\n readonly panelId: string;\n readonly pane: PlayerSystemPaneId;\n readonly anchorId: string;\n readonly interactive: boolean;\n}\n\nexport interface OverlayAlertMarker {\n readonly markerId: string;\n readonly severity: \"info\" | \"warning\" | \"danger\";\n readonly anchorId: string;\n}\n\nexport const PLAYER_SYSTEM_INTERFACE_PACKAGE = \"@plasius/player-system-interface\";\nexport const PLAYER_SYSTEM_INTERFACE_ENV_PREFIX = \"PLAYER_SYSTEM_INTERFACE\";\nexport const PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID =\n \"isekai.player-system.packages.enabled\";\nexport const PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID =\n PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID;\n\nexport const packageDescriptor: PackageDescriptor = Object.freeze({\n packageName: PLAYER_SYSTEM_INTERFACE_PACKAGE,\n featureFlagId: PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID,\n envPrefix: PLAYER_SYSTEM_INTERFACE_ENV_PREFIX,\n summary:\n \"World-space Player System overlays, focus panes, and target-surface contracts for Plasius game experiences.\",\n});\n\nexport function isPlayerSystemInterfaceMode(\n value: string\n): value is PlayerSystemInterfaceMode {\n return value === \"ambient\" || value === \"focused\" || value === \"combat-safe\";\n}\n\nexport function createWorldSpacePanelDefinition(\n input: WorldSpacePanelDefinition\n): WorldSpacePanelDefinition {\n return Object.freeze({ ...input });\n}\n"],"mappings":";AA+BO,IAAM,kCAAkC;AACxC,IAAM,qCAAqC;AAC3C,IAAM,yCACX;AACK,IAAM,0CACX;AAEK,IAAM,oBAAuC,OAAO,OAAO;AAAA,EAChE,aAAa;AAAA,EACb,eAAe;AAAA,EACf,WAAW;AAAA,EACX,SACE;AACJ,CAAC;AAEM,SAAS,4BACd,OACoC;AACpC,SAAO,UAAU,aAAa,UAAU,aAAa,UAAU;AACjE;AAEO,SAAS,gCACd,OAC2B;AAC3B,SAAO,OAAO,OAAO,EAAE,GAAG,MAAM,CAAC;AACnC;","names":[]}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface PackageDescriptor {\n readonly packageName: string;\n readonly featureFlagId: string;\n readonly envPrefix: string;\n readonly summary: string;\n}\n\nexport type OverlayKeyboardPath = \"sequential\" | \"direct-hotkey\" | \"read-only\";\n\nexport interface OverlayAccessibilityContract {\n readonly keyboardPath: OverlayKeyboardPath;\n readonly focusRestorationTarget: \"trigger\" | \"pane-heading\" | \"nearest-anchor\";\n readonly liveRegionMode: \"polite\" | \"assertive\" | \"off\";\n readonly requiresAccessibleName: boolean;\n}\n\nexport interface InterfaceFrameBudget {\n readonly targetFps: number;\n readonly maxFrameMs: number;\n readonly maxInteractivePanelsPerFrame: number;\n}\n\nexport type OverlayHostKind =\n | \"dom-overlay\"\n | \"native-overlay\"\n | \"headless-snapshot\";\n\nexport type OverlayAdapterCapability =\n | \"focus-restoration\"\n | \"live-region\"\n | \"anchor-registry\";\n\nexport interface OverlayHostAdapterContract {\n readonly supportedHosts: readonly OverlayHostKind[];\n readonly requiredCapabilities: readonly OverlayAdapterCapability[];\n readonly forbiddenAssumptions: readonly string[];\n}\n\nexport interface OverlayCompositionScaleContract {\n readonly maxWorldPanels: number;\n readonly maxFocusPanes: number;\n readonly maxAlertMarkers: number;\n readonly maxInteractivePanelsPerFrame: number;\n}\n\nexport interface PlayerSystemInterfaceContract {\n readonly featureFlagId: string;\n readonly accessibility: OverlayAccessibilityContract;\n readonly frameBudget: InterfaceFrameBudget;\n}\n\nexport interface PlayerSystemInterfacePortabilityContract {\n readonly featureFlagId: string;\n readonly hostAdapters: OverlayHostAdapterContract;\n readonly compositionScale: OverlayCompositionScaleContract;\n}\n\nexport interface PlayerSystemInterfaceContractInput {\n readonly featureFlagId?: string;\n readonly accessibility?: Partial<OverlayAccessibilityContract>;\n readonly frameBudget?: Partial<InterfaceFrameBudget>;\n}\n\nexport interface PlayerSystemInterfacePortabilityContractInput {\n readonly featureFlagId?: string;\n readonly hostAdapters?: Partial<OverlayHostAdapterContract>;\n readonly compositionScale?: Partial<OverlayCompositionScaleContract>;\n}\n\nexport type PlayerSystemInterfaceMode = \"ambient\" | \"focused\" | \"combat-safe\";\n\nexport type PlayerSystemPaneId =\n | \"identity\"\n | \"missions\"\n | \"guild-quests\"\n | \"logs\"\n | \"mcc\"\n | \"tutorial\"\n | \"points-store\";\n\nexport interface WorldSpacePanelDefinition {\n readonly panelId: string;\n readonly pane: PlayerSystemPaneId;\n readonly anchorId: string;\n readonly interactive: boolean;\n readonly accessibilityLabel?: string;\n readonly focusOrder?: number;\n}\n\nexport interface OverlayAlertMarker {\n readonly markerId: string;\n readonly severity: \"info\" | \"warning\" | \"danger\";\n readonly anchorId: string;\n}\n\nexport interface WorldSpaceCompositionSample {\n readonly panelCount: number;\n readonly focusPaneCount: number;\n readonly alertMarkerCount: number;\n readonly interactivePanelCount: number;\n}\n\nexport interface InterfaceContractAssessment {\n readonly accepted: boolean;\n readonly violations: readonly string[];\n}\n\nexport const PLAYER_SYSTEM_INTERFACE_PACKAGE = \"@plasius/player-system-interface\";\nexport const PLAYER_SYSTEM_INTERFACE_ENV_PREFIX = \"PLAYER_SYSTEM_INTERFACE\";\nexport const PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID =\n \"isekai.player-system.packages.enabled\";\nexport const PLAYER_SYSTEM_INTERFACE_FEATURE_FLAG_ID =\n PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID;\nexport const PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID =\n \"isekai.player-system.runtime-nfr.enabled\";\nexport const PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID =\n \"isekai.player-system.runtime-portability.enabled\";\n\nexport const packageDescriptor: PackageDescriptor = Object.freeze({\n packageName: PLAYER_SYSTEM_INTERFACE_PACKAGE,\n featureFlagId: PLAYER_SYSTEM_PACKAGES_FEATURE_FLAG_ID,\n envPrefix: PLAYER_SYSTEM_INTERFACE_ENV_PREFIX,\n summary:\n \"World-space Player System overlays, focus panes, and target-surface contracts for Plasius game experiences.\",\n});\n\nexport const defaultPlayerSystemInterfaceContract: PlayerSystemInterfaceContract =\n Object.freeze({\n featureFlagId: PLAYER_SYSTEM_RUNTIME_NFR_FEATURE_FLAG_ID,\n accessibility: Object.freeze({\n keyboardPath: \"sequential\",\n focusRestorationTarget: \"trigger\",\n liveRegionMode: \"polite\",\n requiresAccessibleName: true,\n }),\n frameBudget: Object.freeze({\n targetFps: 60,\n maxFrameMs: 16,\n maxInteractivePanelsPerFrame: 2,\n }),\n });\n\nexport const defaultPlayerSystemInterfacePortabilityContract: PlayerSystemInterfacePortabilityContract =\n Object.freeze({\n featureFlagId: PLAYER_SYSTEM_RUNTIME_PORTABILITY_FEATURE_FLAG_ID,\n hostAdapters: Object.freeze({\n supportedHosts: Object.freeze([\n \"dom-overlay\",\n \"native-overlay\",\n \"headless-snapshot\",\n ] satisfies OverlayHostKind[]),\n requiredCapabilities: Object.freeze([\n \"focus-restoration\",\n \"live-region\",\n \"anchor-registry\",\n ] satisfies OverlayAdapterCapability[]),\n forbiddenAssumptions: Object.freeze([\n \"window-global\",\n \"single-pane-layout\",\n \"absolute-scene-coordinates\",\n ]),\n }),\n compositionScale: Object.freeze({\n maxWorldPanels: 6,\n maxFocusPanes: 3,\n maxAlertMarkers: 8,\n maxInteractivePanelsPerFrame: 2,\n }),\n });\n\nexport function isPlayerSystemInterfaceMode(\n value: string\n): value is PlayerSystemInterfaceMode {\n return value === \"ambient\" || value === \"focused\" || value === \"combat-safe\";\n}\n\nexport function createWorldSpacePanelDefinition(\n input: WorldSpacePanelDefinition\n): WorldSpacePanelDefinition {\n return Object.freeze({ ...input });\n}\n\nexport function createPlayerSystemInterfaceContract(\n input: PlayerSystemInterfaceContractInput = {}\n): PlayerSystemInterfaceContract {\n return Object.freeze({\n featureFlagId:\n input.featureFlagId ?? defaultPlayerSystemInterfaceContract.featureFlagId,\n accessibility: Object.freeze({\n ...defaultPlayerSystemInterfaceContract.accessibility,\n ...input.accessibility,\n }),\n frameBudget: Object.freeze({\n ...defaultPlayerSystemInterfaceContract.frameBudget,\n ...input.frameBudget,\n }),\n });\n}\n\nexport function createPlayerSystemInterfacePortabilityContract(\n input: PlayerSystemInterfacePortabilityContractInput = {}\n): PlayerSystemInterfacePortabilityContract {\n return Object.freeze({\n featureFlagId:\n input.featureFlagId ??\n defaultPlayerSystemInterfacePortabilityContract.featureFlagId,\n hostAdapters: Object.freeze({\n ...defaultPlayerSystemInterfacePortabilityContract.hostAdapters,\n ...input.hostAdapters,\n supportedHosts: Object.freeze([\n ...(input.hostAdapters?.supportedHosts ??\n defaultPlayerSystemInterfacePortabilityContract.hostAdapters\n .supportedHosts),\n ]),\n requiredCapabilities: Object.freeze([\n ...(input.hostAdapters?.requiredCapabilities ??\n defaultPlayerSystemInterfacePortabilityContract.hostAdapters\n .requiredCapabilities),\n ]),\n forbiddenAssumptions: Object.freeze([\n ...(input.hostAdapters?.forbiddenAssumptions ??\n defaultPlayerSystemInterfacePortabilityContract.hostAdapters\n .forbiddenAssumptions),\n ]),\n }),\n compositionScale: Object.freeze({\n ...defaultPlayerSystemInterfacePortabilityContract.compositionScale,\n ...input.compositionScale,\n }),\n });\n}\n\nexport function assessPlayerSystemInterfaceComposition(\n sample: WorldSpaceCompositionSample,\n contract: PlayerSystemInterfacePortabilityContract = defaultPlayerSystemInterfacePortabilityContract\n): InterfaceContractAssessment {\n const violations: string[] = [];\n\n if (sample.panelCount > contract.compositionScale.maxWorldPanels) {\n violations.push(\"panelCount\");\n }\n\n if (sample.focusPaneCount > contract.compositionScale.maxFocusPanes) {\n violations.push(\"focusPaneCount\");\n }\n\n if (sample.alertMarkerCount > contract.compositionScale.maxAlertMarkers) {\n violations.push(\"alertMarkerCount\");\n }\n\n if (\n sample.interactivePanelCount >\n contract.compositionScale.maxInteractivePanelsPerFrame\n ) {\n violations.push(\"interactivePanelCount\");\n }\n\n return Object.freeze({\n accepted: violations.length === 0,\n violations: Object.freeze(violations),\n });\n}\n"],"mappings":"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","names":[]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plasius/player-system-interface",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "World-space Player System overlays, focus panes, and target-surface contracts for Plasius game experiences",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -54,17 +54,17 @@
54
54
  "homepage": "https://github.com/Plasius-LTD/player-system-interface#readme",
55
55
  "devDependencies": {
56
56
  "@eslint/js": "^10.0.1",
57
- "@types/node": "^25.7.0",
58
- "@typescript-eslint/eslint-plugin": "^8.59.3",
59
- "@typescript-eslint/parser": "^8.59.3",
60
- "@vitest/coverage-v8": "^4.1.6",
61
- "eslint": "^10.3.0",
57
+ "@types/node": "^25.9.1",
58
+ "@typescript-eslint/eslint-plugin": "^8.59.4",
59
+ "@typescript-eslint/parser": "^8.59.4",
60
+ "@vitest/coverage-v8": "^4.1.7",
61
+ "eslint": "^10.4.0",
62
62
  "globals": "^17.6.0",
63
63
  "rimraf": "^6.0.1",
64
64
  "tsup": "^8.5.1",
65
- "tsx": "^4.21.0",
65
+ "tsx": "^4.22.3",
66
66
  "typescript": "^6.0.3",
67
- "vitest": "^4.1.6"
67
+ "vitest": "^4.1.7"
68
68
  },
69
69
  "publishConfig": {
70
70
  "access": "public"