@iwsdk/create 0.5.3 → 1.0.0-rc.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/dist/cli.js +7224 -216
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
- package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
- package/dist/guidance/claude/.claude/settings.json +6 -2
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/CLAUDE.md +2 -141
- package/dist/guidance/codex/.codex/config.toml +1 -1
- package/dist/guidance/common/AGENTS.md +96 -37
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/public/ui/welcome.uikitml +0 -19
- package/dist/template/common/src/robot.ts +5 -0
- package/dist/template/common/vite.config.ts +18 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
- package/dist/template/common-js/src/robot.js +5 -0
- package/dist/template/common-js/vite.config.js +18 -0
- package/package.json +8 -7
- package/scripts/verify-release-ready.mjs +25 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
- /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
# Planner path
|
|
2
|
+
|
|
3
|
+
Deliver the requested experience with the smallest reliable loop. Preserve the
|
|
4
|
+
user's exact observable contract, use IWSDK-native workflows, verify the real
|
|
5
|
+
runtime, and stop when the contract is proven.
|
|
6
|
+
|
|
7
|
+
## Default operating mode
|
|
8
|
+
|
|
9
|
+
- Work autonomously when the task is already specific. Do not pause for design
|
|
10
|
+
approval unless a missing choice materially changes the product.
|
|
11
|
+
- Keep one compact plan in the conversation or task list. Do not create
|
|
12
|
+
`design/`, pipeline-state, deck, concept-art, architecture, verification, or
|
|
13
|
+
retrospective files unless the user explicitly requests them.
|
|
14
|
+
- Do not scaffold a nested app. Treat the generated project in the working
|
|
15
|
+
directory as the starting point.
|
|
16
|
+
- Do not run an untouched-scaffold demo. Inspect the generated project briefly
|
|
17
|
+
and begin the requested implementation.
|
|
18
|
+
- Use subagents only for genuinely independent work that saves wall time. Do
|
|
19
|
+
not spawn a planner, documentation, or review subagent by default.
|
|
20
|
+
|
|
21
|
+
## 1. Extract the executable contract
|
|
22
|
+
|
|
23
|
+
Before editing, reduce the prompt to a short checklist:
|
|
24
|
+
|
|
25
|
+
1. exact files, scene node IDs, UIKit element IDs, component names, and fields;
|
|
26
|
+
2. explicit initial values and state transitions;
|
|
27
|
+
3. interaction paths that must work in the live app;
|
|
28
|
+
4. visible states and required framing/legibility;
|
|
29
|
+
5. build and runtime evidence needed before stopping.
|
|
30
|
+
|
|
31
|
+
Treat exact values as data, not implications. If a required field value equals
|
|
32
|
+
the component default, still serialize it explicitly in authored scene data.
|
|
33
|
+
For example, a required profile `A` must be written as `profileId: "A"`, not
|
|
34
|
+
left implicit because `A` is the schema default.
|
|
35
|
+
|
|
36
|
+
When the prompt names live runtime objects, assign those runtime `.name`
|
|
37
|
+
values exactly during initialization and verify them in the runtime hierarchy.
|
|
38
|
+
UIKit element IDs alone do not satisfy a runtime-name requirement.
|
|
39
|
+
|
|
40
|
+
## 2. Inspect once, then ground only uncertainty
|
|
41
|
+
|
|
42
|
+
Read the existing entry point, project config, asset/component registries,
|
|
43
|
+
scene, and relevant scoped rules. Use precise `npx @iwsdk/cli reference` queries
|
|
44
|
+
only for APIs or file formats that are genuinely uncertain.
|
|
45
|
+
|
|
46
|
+
Convert FBX, OBJ, and other source model formats before registering them: in
|
|
47
|
+
Blender use **File → Import**, then **File → Export → glTF 2.0**, and add the
|
|
48
|
+
resulting GLB/GLTF to the asset manifest.
|
|
49
|
+
|
|
50
|
+
For a fresh scaffold that needs native scene composition and UIKitML, use this
|
|
51
|
+
exact fast path before broad discovery:
|
|
52
|
+
|
|
53
|
+
1. read the applicable scoped `AGENTS.md`, then exactly these scaffold rules
|
|
54
|
+
when present: `.claude/rules/scene-json.md`, `ecs-api.md`, `uikitml.md`, and
|
|
55
|
+
`assets-and-manifest.md`; do not list directories first;
|
|
56
|
+
2. in one bounded shell call, print `package.json`, `iwsdk.config.json`, the
|
|
57
|
+
small scaffold `src/*.ts` files, the authored scene JSON, and UIKitML;
|
|
58
|
+
3. use `iwsdk-build-model` for every new or materially changed model, then use
|
|
59
|
+
`iwsdk-compose-scene` for scene placement, lighting, environment, and cameras;
|
|
60
|
+
load `iwsdk-ui/SKILL.md` only when UIKitML is part of the request;
|
|
61
|
+
4. create or replace the first implementation files immediately, then let
|
|
62
|
+
typecheck/runtime errors identify any
|
|
63
|
+
additional API question.
|
|
64
|
+
|
|
65
|
+
The first edit is a checkpoint: reach it within 8 tool calls after loading this
|
|
66
|
+
playbook. Do not inspect generated declarations, search node_modules, or invoke
|
|
67
|
+
another specialist before it. If one framework boundary remains unclear, write
|
|
68
|
+
the straightforward typed slice, run npm run --if-present typecheck, and investigate only the
|
|
69
|
+
concrete compiler error. After the focused references, edit before optional
|
|
70
|
+
lookup.
|
|
71
|
+
|
|
72
|
+
For the bounded scaffold read, prefer one command shaped like this over a
|
|
73
|
+
series of individual reads (adjust globs only when the project differs):
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
for f in package.json iwsdk.config.json src/*.ts public/scenes/*.json public/ui/*.uikitml; do
|
|
77
|
+
echo "--- $f"; sed -n '1,260p' "$f"
|
|
78
|
+
done
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
For a compact greenfield scene, keep the default player spawn unless the prompt
|
|
82
|
+
explicitly requires another spawn. Do not inspect schemas to add an optional
|
|
83
|
+
`player` block. Keep the standing volume around the origin clear, place the
|
|
84
|
+
experience in front of it (normally negative Z), and use this document shape:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"version": "iwsdk.scene.v1",
|
|
89
|
+
"units": "meters",
|
|
90
|
+
"components": {},
|
|
91
|
+
"resources": {},
|
|
92
|
+
"nodes": [],
|
|
93
|
+
"authoring": { "views": [] }
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Use these stable high-friction recipes directly; do not rediscover them in
|
|
98
|
+
`node_modules`:
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
const Profiles = { A: 'A', B: 'B', C: 'C' } as const;
|
|
102
|
+
const Example = createComponent('Example', {
|
|
103
|
+
profileId: { type: Types.Enum, default: Profiles.A, enum: Profiles },
|
|
104
|
+
occupant: { type: Types.Entity, default: null },
|
|
105
|
+
active: { type: Types.Boolean, default: false },
|
|
106
|
+
elapsed: { type: Types.Float32, default: 0 },
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
const panel = world.requireSceneObject<UIKitMLAsset>('ControlPanel');
|
|
110
|
+
const status = panel.requireElementById<UIKit.Text>('StatusText');
|
|
111
|
+
const button = panel.requireElementById('Btn_Action');
|
|
112
|
+
status.name = 'StatusText';
|
|
113
|
+
button.name = 'Btn_Action';
|
|
114
|
+
button.addEventListener('click', onAction);
|
|
115
|
+
cleanupFuncs.push(() => button.removeEventListener('click', onAction));
|
|
116
|
+
|
|
117
|
+
export class ExampleSystem extends createSystem({
|
|
118
|
+
examples: { required: [Example] },
|
|
119
|
+
held: { required: [Example, Grabbed] },
|
|
120
|
+
}) {
|
|
121
|
+
init(): void {
|
|
122
|
+
const onGrab = (entity: Entity) => entity.setValue(Example, 'active', true);
|
|
123
|
+
const onRelease = (entity: Entity) =>
|
|
124
|
+
entity.setValue(Example, 'active', false);
|
|
125
|
+
const offGrab = this.queries.held.subscribe('qualify', onGrab);
|
|
126
|
+
const offRelease = this.queries.held.subscribe('disqualify', onRelease);
|
|
127
|
+
this.cleanupFuncs.push(offGrab, offRelease);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
update(delta: number): void {
|
|
131
|
+
for (const entity of this.queries.examples.entities) {
|
|
132
|
+
const active = entity.getValue(Example, 'active');
|
|
133
|
+
const elapsed = entity.getValue(Example, 'elapsed') ?? 0;
|
|
134
|
+
if (active) entity.setValue(Example, 'elapsed', elapsed + delta);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
- Declare systems with `class X extends createSystem({ queryName: { required: [...] } })`.
|
|
141
|
+
Iterate `this.queries.queryName.entities`, and use
|
|
142
|
+
`entity.getValue(Component, field)` / `entity.setValue(Component, field, value)`.
|
|
143
|
+
Query `subscribe` returns an unsubscribe function for `cleanupFuncs`.
|
|
144
|
+
- Author an empty entity reference as `null` in scene JSON.
|
|
145
|
+
- Put `OneHandGrabbable` on authored nodes that need proximity grabbing. Treat
|
|
146
|
+
`Grabbed` as a runtime tag; use qualify/disqualify transitions for lifecycle
|
|
147
|
+
handling and `GrabSystem.forceRelease(entity)` for reset.
|
|
148
|
+
- When a slot accepts only one entity, guard against replacement: if its current
|
|
149
|
+
entity is non-null and differs from the released entity, leave both unchanged.
|
|
150
|
+
- Resolve authored entities and objects with `world.requireSceneEntity(nodeId)`
|
|
151
|
+
and `world.requireSceneObject(nodeId)`.
|
|
152
|
+
- Import ECS, UIKit, grab helpers, and Three.js runtime classes from
|
|
153
|
+
`@iwsdk/core`; IWSDK re-exports the supported runtime surface.
|
|
154
|
+
- For a live UIKit ray click, aim with `npx @iwsdk/cli xr look-at`, then use
|
|
155
|
+
`npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'`.
|
|
156
|
+
Do not rederive pointer internals or manually pulse select unless diagnosing
|
|
157
|
+
a concrete helper failure.
|
|
158
|
+
|
|
159
|
+
Avoid broad repeated discovery:
|
|
160
|
+
|
|
161
|
+
- do not enumerate the same command family or dependency tree multiple times;
|
|
162
|
+
- do not read generated bundles or large reference files when a focused API or
|
|
163
|
+
example query answers the question;
|
|
164
|
+
- do not repeat successful status, hierarchy, or capability probes without a
|
|
165
|
+
state change that requires it.
|
|
166
|
+
|
|
167
|
+
Specialist skills are optional focused references, not mandatory phases. Use
|
|
168
|
+
only the skills needed by the contract, normally at most once each:
|
|
169
|
+
|
|
170
|
+
- `iwsdk-build-model` for new or materially changed model geometry, materials,
|
|
171
|
+
hierarchy, or surface detail;
|
|
172
|
+
- `iwsdk-compose-scene` for scene JSON, placement, cross-asset contacts,
|
|
173
|
+
lighting, environment, or camera views after model work is complete;
|
|
174
|
+
- `iwsdk-ui` for UIKitML authoring or layout debugging;
|
|
175
|
+
- `iwsdk-grab` / `iwsdk-ray` for unfamiliar live interaction simulation;
|
|
176
|
+
- `iwsdk-debug` after a concrete runtime failure.
|
|
177
|
+
|
|
178
|
+
Pass a concise problem statement to a specialist. Do not paste the full user
|
|
179
|
+
prompt, ask it to run another end-to-end plan, or invoke overlapping skills for
|
|
180
|
+
the same question.
|
|
181
|
+
|
|
182
|
+
## 3. Implement one coherent vertical slice
|
|
183
|
+
|
|
184
|
+
Build the smallest structure that covers the whole contract:
|
|
185
|
+
|
|
186
|
+
1. native scene assets and deliberate hero/panel framing;
|
|
187
|
+
2. component schemas and explicit authored values;
|
|
188
|
+
3. interaction/state systems;
|
|
189
|
+
4. UIKitML and runtime control wiring;
|
|
190
|
+
5. visible state feedback.
|
|
191
|
+
|
|
192
|
+
Prefer IWSDK built-ins and project-local patterns. Keep systems small, register
|
|
193
|
+
cleanup functions, avoid per-frame allocation, and preserve feature-flag
|
|
194
|
+
prerequisites. Do not create process documents while code is incomplete.
|
|
195
|
+
|
|
196
|
+
Run `npm run --if-present typecheck` after the coherent slice exists, then fix errors in a
|
|
197
|
+
batch. Do not typecheck after every small edit. Run the production build near
|
|
198
|
+
the end and again only after a change that can affect it.
|
|
199
|
+
|
|
200
|
+
## 4. Verify the actual contract
|
|
201
|
+
|
|
202
|
+
Match verification depth to the app and its risk. A simple single-scene app
|
|
203
|
+
needs direct evidence for its few success criteria; multi-system behavior,
|
|
204
|
+
physics, deployment, and interactions with meaningful failure modes need
|
|
205
|
+
broader scenarios and stronger evidence.
|
|
206
|
+
|
|
207
|
+
After the coherent vertical slice typechecks, start one managed dev session
|
|
208
|
+
and keep it alive while iterating. The developer owns headed versus headless
|
|
209
|
+
mode: announce a proposed mode change before restarting rather than silently
|
|
210
|
+
replacing their visible collaboration window. Do not start an untouched or
|
|
211
|
+
knowingly non-typechecking app. Exercise the real paths rather than inferring
|
|
212
|
+
behavior from code. Confirm `npx @iwsdk/cli xr status` is active before making pose,
|
|
213
|
+
controller/hand alignment, or immersive-interaction claims; a flat screenshot
|
|
214
|
+
outside XR cannot prove them.
|
|
215
|
+
|
|
216
|
+
Verify:
|
|
217
|
+
|
|
218
|
+
- initial ECS state and explicit authored values;
|
|
219
|
+
- every interaction required by the acceptance contract;
|
|
220
|
+
- empty, rejected, boundary, or exclusivity guards when applicable;
|
|
221
|
+
- timed transitions and visible state feedback;
|
|
222
|
+
- reset of affected state, transforms, flags, timers, and references;
|
|
223
|
+
- exact runtime hierarchy names for addressable controls.
|
|
224
|
+
|
|
225
|
+
When the contract includes an exclusive slot or station, prove that a second
|
|
226
|
+
object cannot silently replace the current occupant.
|
|
227
|
+
|
|
228
|
+
Use compact CLI scripts to group related assertions. Capture screenshots at
|
|
229
|
+
the requested key states, not after every minor change.
|
|
230
|
+
|
|
231
|
+
Once the dev session is ready, target at most 24 shell-tool calls for the
|
|
232
|
+
entire verification pass. Batch the contract into a few coherent scenarios,
|
|
233
|
+
for example: initial state and guard behavior, successful primary interaction,
|
|
234
|
+
rejected or boundary behavior, and reset/runtime-name closeout. Each block
|
|
235
|
+
should perform its input sequence, query affected state, and print a compact
|
|
236
|
+
PASS/FAIL summary. After a failure, diagnose once and rerun only that block.
|
|
237
|
+
|
|
238
|
+
Keep context lean while iterating:
|
|
239
|
+
|
|
240
|
+
- do not re-read a file after a successful write or edit unless a later tool
|
|
241
|
+
reports a concrete mismatch; use a targeted range or search when only one
|
|
242
|
+
section is uncertain;
|
|
243
|
+
- project large CLI responses down to the exact fields being checked and cap
|
|
244
|
+
logs/search output;
|
|
245
|
+
- save evidence screenshots to disk, but do not load every full-resolution
|
|
246
|
+
image into model context. Image reads are expensive and can force context
|
|
247
|
+
compaction.
|
|
248
|
+
|
|
249
|
+
## 5. Visual quality gate
|
|
250
|
+
|
|
251
|
+
Before finishing, inspect the same hero/runtime view a reviewer will see:
|
|
252
|
+
|
|
253
|
+
- the complete experience fills the frame at a useful scale;
|
|
254
|
+
- primary objects and controls are visually distinguishable;
|
|
255
|
+
- important text and controls are readable from the intended viewpoint;
|
|
256
|
+
- required states differ immediately through color, text, motion, or emissive
|
|
257
|
+
feedback;
|
|
258
|
+
- no unintended starter content, severe clipping, empty space, or back-facing UI
|
|
259
|
+
remains.
|
|
260
|
+
|
|
261
|
+
If the app is correct but the panel is tiny or the scene is too distant, fix
|
|
262
|
+
camera/framing before adding decorative complexity.
|
|
263
|
+
|
|
264
|
+
Use at most two visual reads by default: one early hero frame when composition
|
|
265
|
+
is uncertain, and one final inspection. Prefer a compact contact sheet of the
|
|
266
|
+
required states for the final read. If no contact-sheet tool is available,
|
|
267
|
+
inspect the hero frame plus the visually riskiest active state and prove the
|
|
268
|
+
remaining state changes through exact runtime text/color/state assertions.
|
|
269
|
+
Exceed this budget only to diagnose a specific visible defect, and replace an
|
|
270
|
+
earlier read rather than accumulating near-duplicate screenshots.
|
|
271
|
+
|
|
272
|
+
Keep original screenshots at evidence resolution, but load only a bounded
|
|
273
|
+
inspection copy into model context. Use an image tool already present in the
|
|
274
|
+
environment to limit an individual frame to roughly 640 pixels on its long edge
|
|
275
|
+
or a contact sheet to 1024 by 1024. Do not install a dependency only for this.
|
|
276
|
+
|
|
277
|
+
## 6. Targeted closeout, then stop
|
|
278
|
+
|
|
279
|
+
Once live assertions pass:
|
|
280
|
+
|
|
281
|
+
1. check the authored scene for every exact ID, component, and explicit value;
|
|
282
|
+
2. check runtime names and event-listener cleanup;
|
|
283
|
+
3. run `npm run --if-present typecheck` and `npm run build`;
|
|
284
|
+
4. re-run only assertions affected by the final fixes;
|
|
285
|
+
5. leave the app reset to its initial state and report concise evidence.
|
|
286
|
+
|
|
287
|
+
Do not launch the project code-reviewer by default. Use it only when a live or
|
|
288
|
+
build failure remains unexplained, the implementation uses an unfamiliar
|
|
289
|
+
framework boundary, or the user explicitly requests review. Do not apply
|
|
290
|
+
style-only review changes after the quality gates pass.
|
|
291
|
+
|
|
292
|
+
## Budget and stopping rules
|
|
293
|
+
|
|
294
|
+
- By roughly 60% of the available session, the full vertical slice should
|
|
295
|
+
exist and typecheck.
|
|
296
|
+
- By roughly 75%, switch from feature work to runtime verification.
|
|
297
|
+
- By roughly 85%, freeze optional polish and close exact contract gaps.
|
|
298
|
+
- Prefer one proven implementation over alternate architectures, redundant
|
|
299
|
+
screenshots, repeated reviews, or speculative cleanup.
|
|
300
|
+
- Stop when static contract, production build, live paths, and visual gate pass.
|
|
301
|
+
|
|
302
|
+
The output is the working IWSDK app and concise final evidence—not a record of
|
|
303
|
+
the process used to produce it.
|
|
@@ -1,128 +1,51 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: iwsdk-grab
|
|
3
|
-
description:
|
|
4
|
-
argument-hint:
|
|
3
|
+
description: Use emulated XR controllers to verify proximity grabbing for OneHandGrabbable and TwoHandsGrabbable objects. Use for pick up, move, release, or regression-test requests involving near-hand grab with the squeeze button.
|
|
4
|
+
argument-hint: '(use the current request)'
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
# Grab
|
|
7
|
+
# IWSDK Proximity Grab
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Use this workflow only for `OneHandGrabbable` or `TwoHandsGrabbable`. A
|
|
10
|
+
`DistanceGrabbable` uses the ray/trigger path instead.
|
|
10
11
|
|
|
11
|
-
|
|
12
|
+
## Execute the requested path
|
|
12
13
|
|
|
13
|
-
|
|
14
|
+
1. Check XR session state and enter XR only when inactive.
|
|
15
|
+
2. Find the named live entity and query its components and transform. If it is
|
|
16
|
+
absent, list nearby grabbable matches once and stop with the evidence.
|
|
17
|
+
3. Confirm it has `OneHandGrabbable` or `TwoHandsGrabbable`. Do not guess the
|
|
18
|
+
interaction type from its name.
|
|
19
|
+
4. Animate the requested controller to the object. Default to the right
|
|
20
|
+
controller only when the user did not choose a hand.
|
|
21
|
+
5. Press and hold squeeze/grip button index `1`:
|
|
14
22
|
|
|
15
|
-
|
|
23
|
+
```json
|
|
24
|
+
{"device":"controller-right","buttons":[{"index":1,"value":1}]}
|
|
25
|
+
```
|
|
16
26
|
|
|
17
|
-
|
|
27
|
+
6. Query the entity for `Grabbed` or another requested observable state. If the
|
|
28
|
+
grab did not qualify, make one focused correction to controller position and
|
|
29
|
+
retry once.
|
|
30
|
+
7. If movement was requested, animate the held controller to the destination.
|
|
31
|
+
8. Release squeeze with index `1`, value `0`, then query the final transform or
|
|
32
|
+
state. Move the controller away only when overlap would interfere with the
|
|
33
|
+
result.
|
|
18
34
|
|
|
19
|
-
|
|
35
|
+
Do not use trigger index `0`, `xr select`, or teleport-style device mutation for
|
|
36
|
+
proximity grab. Do not edit source merely to make an existing named entity easier
|
|
37
|
+
to locate; report missing runtime identity when that is the actual defect.
|
|
20
38
|
|
|
21
|
-
|
|
22
|
-
xr_get_session_status → if not sessionActive → xr_accept_session
|
|
23
|
-
```
|
|
39
|
+
## Evidence and stopping
|
|
24
40
|
|
|
25
|
-
|
|
41
|
+
Prefer measured ECS state over screenshots. Capture one runtime image only when
|
|
42
|
+
the user requested visual evidence or placement must be judged. Batch related
|
|
43
|
+
queries and avoid repeating session, hierarchy, or transform discovery after a
|
|
44
|
+
successful read.
|
|
26
45
|
|
|
27
|
-
|
|
46
|
+
When the request names an artifact path, save it directly with
|
|
47
|
+
`npx @iwsdk/cli browser screenshot --output-file <path>`. A screenshot returned only
|
|
48
|
+
to model context does not satisfy a requested file deliverable.
|
|
28
49
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
If the object is not found, search `OneHandGrabbable` and `TwoHandsGrabbable`
|
|
34
|
-
entities, report the available matches, and stop.
|
|
35
|
-
|
|
36
|
-
### Step 3: Get its transform
|
|
37
|
-
|
|
38
|
-
Read the object's Transform position from the queried entity.
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
ecs_query_entity(entityIndex) → Transform.position
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
### Step 4: Animate controller to target
|
|
45
|
-
|
|
46
|
-
Animate the controller to the object's position. Default to `"controller-right"` unless the user specified left.
|
|
47
|
-
|
|
48
|
-
```
|
|
49
|
-
xr_animate_to({
|
|
50
|
-
device: "controller-right",
|
|
51
|
-
position: { x, y, z },
|
|
52
|
-
duration: 0.5,
|
|
53
|
-
})
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
### Step 5: Engage grip
|
|
57
|
-
|
|
58
|
-
OneHandGrabbable and TwoHandsGrabbable are proximity-based and use the **squeeze/grip button (index 1)**, not the trigger.
|
|
59
|
-
|
|
60
|
-
```
|
|
61
|
-
xr_set_gamepad_state({
|
|
62
|
-
device: "controller-right",
|
|
63
|
-
buttons: [{ index: 1, value: 1 }],
|
|
64
|
-
})
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
The object is now grabbed. If the user only asked to grab (not move), stop here.
|
|
68
|
-
|
|
69
|
-
## Optional Extensions
|
|
70
|
-
|
|
71
|
-
Apply these based on the user's request.
|
|
72
|
-
|
|
73
|
-
### Step 6: Move to destination
|
|
74
|
-
|
|
75
|
-
If the user specified a destination position, animate the controller there. If no position was given but the user asked to "move" the object, animate it to in front of the headset.
|
|
76
|
-
|
|
77
|
-
To find "in front of headset": `xr_get_transform({ "device": "headset" })` → place at `(head.x, head.y - 0.2, head.z - 0.5)` adjusted for head orientation.
|
|
78
|
-
|
|
79
|
-
```
|
|
80
|
-
xr_animate_to({
|
|
81
|
-
device: "controller-right",
|
|
82
|
-
position: { x, y, z },
|
|
83
|
-
duration: 0.5,
|
|
84
|
-
})
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
### Step 7: Release grip
|
|
88
|
-
|
|
89
|
-
Release the squeeze button to drop the object.
|
|
90
|
-
|
|
91
|
-
```
|
|
92
|
-
xr_set_gamepad_state({
|
|
93
|
-
device: "controller-right",
|
|
94
|
-
buttons: [{ index: 1, value: 0 }],
|
|
95
|
-
})
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
### Step 8: Return controller
|
|
99
|
-
|
|
100
|
-
Animate the controller back to its resting position so it's not overlapping the dropped object.
|
|
101
|
-
|
|
102
|
-
```
|
|
103
|
-
xr_animate_to({
|
|
104
|
-
device: "controller-right",
|
|
105
|
-
position: { x: 0.2, y: 1.4, z: -0.3 },
|
|
106
|
-
duration: 0.5,
|
|
107
|
-
})
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
Default resting positions: right `(0.2, 1.4, -0.3)`, left `(-0.2, 1.4, -0.3)`.
|
|
111
|
-
|
|
112
|
-
### Step 9: Verify
|
|
113
|
-
|
|
114
|
-
Take a screenshot to confirm the result.
|
|
115
|
-
|
|
116
|
-
```
|
|
117
|
-
browser_screenshot
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
The screenshot command is runtime-only. If the editor is visible, the managed
|
|
121
|
-
workspace switches to runtime before capture.
|
|
122
|
-
|
|
123
|
-
## Notes
|
|
124
|
-
|
|
125
|
-
- **Never use `xr_set_device_state` to move controllers** — it teleports instead of animating, which can break grab state.
|
|
126
|
-
- **Never use `xr_select` or trigger (button index 0) for grabs** — OneHandGrabbable/TwoHandsGrabbable respond to squeeze (button index 1).
|
|
127
|
-
- **DistanceGrabbable is different** — it uses ray-based selection, not proximity. This skill does not cover DistanceGrabbable.
|
|
128
|
-
- If the object lacks a name in the hierarchy, suggest adding `mesh.name = "MyObject"` in code before `createTransformEntity`.
|
|
50
|
+
Stop once the requested grab/move/release path and final state are proven. Leave
|
|
51
|
+
the controller released and the XR session in the state the user requested.
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-hosting
|
|
3
|
+
description: Publish an IWSDK app to a public HTTPS origin so it can be installed as a PWA and packaged for the Meta Horizon Store. Use when deploying, hosting, or publishing the app, choosing a host, or when a file (web manifest, icons, .well-known/assetlinks.json) must reach an already-hosted site. Always asks first whether hosting already exists — recommends Vercel if not, and pauses with concrete upload steps if it does.
|
|
4
|
+
argument-hint: '[domain, host name, or deploy request]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# PWA Hosting
|
|
8
|
+
|
|
9
|
+
Packaging a Quest APK reads the app over the network, not off disk:
|
|
10
|
+
`bubblewrap` fetches the web manifest and icons from the live origin, and the
|
|
11
|
+
Trusted Web Activity refuses to launch until Digital Asset Links are reachable
|
|
12
|
+
there too. So the origin — call it `<DOMAIN>` — comes first, and every later
|
|
13
|
+
step depends on files actually being served from it.
|
|
14
|
+
|
|
15
|
+
User request is in `$ARGUMENTS`.
|
|
16
|
+
|
|
17
|
+
## 1. Ask about hosting before doing anything else
|
|
18
|
+
|
|
19
|
+
**Never assume.** Ask the developer, up front, whether the app is already
|
|
20
|
+
deployed — with a structured question tool (AskUserQuestion) if the harness has
|
|
21
|
+
one, otherwise as a plain question. Do not deploy anything, do not pick a host,
|
|
22
|
+
and do not run a deploy CLI until this is answered.
|
|
23
|
+
|
|
24
|
+
> Is this app already deployed to a public HTTPS URL?
|
|
25
|
+
>
|
|
26
|
+
> - **Not deployed yet — recommend a host** → Route A
|
|
27
|
+
> - **Already hosted / host already chosen** (Netlify, Cloudflare Pages, GitHub
|
|
28
|
+
> Pages, S3+CloudFront, Firebase, own nginx/Apache server, internal CDN…) →
|
|
29
|
+
> Route B
|
|
30
|
+
> - **Deployed, but open to moving it** → describe both, then let them pick
|
|
31
|
+
|
|
32
|
+
If they answer with a URL, treat it as Route B and use that URL as `<DOMAIN>`.
|
|
33
|
+
If they are unreachable and you must proceed autonomously, take Route A, and
|
|
34
|
+
mark the choice `[ASSUMED]` in whatever plan or report you are writing.
|
|
35
|
+
|
|
36
|
+
## 2. Route A — no host yet: recommend Vercel
|
|
37
|
+
|
|
38
|
+
Recommend Vercel, and say why in one line: it detects Vite with no config,
|
|
39
|
+
serves `dist/` over HTTPS with a stable public alias, keeps `public/` dotfolders
|
|
40
|
+
like `.well-known/` intact, and redeploys with one command — which matters
|
|
41
|
+
because asset links force a second publish later.
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npm run build # → dist/
|
|
45
|
+
npx -y vercel@latest whoami # auth check
|
|
46
|
+
npx -y vercel@latest teams ls # find <team-slug>
|
|
47
|
+
npx -y vercel@latest deploy --prod --yes --scope <team-slug>
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Use the **canonical alias** (`https://<project>.vercel.app`) as `<DOMAIN>`, not
|
|
51
|
+
the hashed per-deploy URL — under team deployment protection the hashed URL
|
|
52
|
+
returns 401 and every downstream fetch fails. Full walkthrough, first-run login,
|
|
53
|
+
and the redeploy rule: [`references/vercel.md`](references/vercel.md).
|
|
54
|
+
|
|
55
|
+
Then run the [contract check](#4-the-contract-what-must-be-reachable).
|
|
56
|
+
|
|
57
|
+
## 3. Route B — host already chosen: pause and hand off
|
|
58
|
+
|
|
59
|
+
The developer owns the host, so **you do not publish — you prepare files and
|
|
60
|
+
stop.** Every time something new has to reach `<DOMAIN>`, run the handoff below
|
|
61
|
+
rather than guessing at their pipeline.
|
|
62
|
+
|
|
63
|
+
Publishing to an existing host happens at least **twice**, and the second one is
|
|
64
|
+
easy to forget:
|
|
65
|
+
|
|
66
|
+
| # | When | What must reach `<DOMAIN>` |
|
|
67
|
+
| - | ---- | -------------------------- |
|
|
68
|
+
| 1 | after the manifest + icons exist | the whole built `dist/` |
|
|
69
|
+
| 2 | after the signing keystore exists | `dist/.well-known/assetlinks.json` (rebuild first) |
|
|
70
|
+
|
|
71
|
+
A third happens for any later web-only fix — those need only a republish, never
|
|
72
|
+
a new APK.
|
|
73
|
+
|
|
74
|
+
### Upload handoff protocol
|
|
75
|
+
|
|
76
|
+
Run this at each row above. Keep it short and literal; the developer should be
|
|
77
|
+
able to act without asking a follow-up question.
|
|
78
|
+
|
|
79
|
+
1. **Build first.** `npm run build`. Vite copies `public/` — including
|
|
80
|
+
dotfolders like `.well-known/` — verbatim into `dist/`.
|
|
81
|
+
2. **List the exact files and their exact destination URLs.** Local path →
|
|
82
|
+
public URL, one per line. Never say "upload the assets".
|
|
83
|
+
3. **Give the concrete steps for their host**, not generic advice — the command
|
|
84
|
+
for their CLI, or the click path for their dashboard. Per-host recipes and
|
|
85
|
+
gotchas (dotfolder stripping, MIME types, subpath hosting, cache TTLs) are in
|
|
86
|
+
[`references/existing-hosts.md`](references/existing-hosts.md). If the host is
|
|
87
|
+
one you do not recognize, ask how they normally publish and adapt.
|
|
88
|
+
4. **Offer to run it — do not assume you can.** Only run their deploy command
|
|
89
|
+
yourself if they confirm the CLI is installed and authenticated in this
|
|
90
|
+
environment. Otherwise they run it; suggest they can paste it into this
|
|
91
|
+
session prefixed with `!`.
|
|
92
|
+
5. **Stop and wait.** Do not continue to the next pipeline step on the
|
|
93
|
+
assumption the upload happened.
|
|
94
|
+
6. **Verify yourself once they say it is live**, with the checks in §4. If a
|
|
95
|
+
check fails, report the failing URL and status code and hand back — a wrong
|
|
96
|
+
guess here surfaces much later as "the TWA will not launch".
|
|
97
|
+
|
|
98
|
+
Handoff message template:
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
Ready to publish. Please upload these to <DOMAIN>:
|
|
102
|
+
|
|
103
|
+
dist/manifest.webmanifest → https://<DOMAIN>/manifest.webmanifest
|
|
104
|
+
dist/icons/icon-192.png → https://<DOMAIN>/icons/icon-192.png
|
|
105
|
+
dist/icons/icon-512.png → https://<DOMAIN>/icons/icon-512.png
|
|
106
|
+
dist/icons/icon-512-maskable.png → https://<DOMAIN>/icons/icon-512-maskable.png
|
|
107
|
+
(or simply publish all of dist/ — these are already inside it)
|
|
108
|
+
|
|
109
|
+
On <host>, that is:
|
|
110
|
+
<the one command, or the exact dashboard click path>
|
|
111
|
+
|
|
112
|
+
Tell me when it is live and I will verify, then continue with packaging.
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## 4. The contract: what must be reachable
|
|
116
|
+
|
|
117
|
+
Whichever route was taken, `<DOMAIN>` must satisfy all of this before
|
|
118
|
+
`bubblewrap update` runs. Check it yourself — do not take "it is deployed" as
|
|
119
|
+
proof.
|
|
120
|
+
|
|
121
|
+
| URL | Expected |
|
|
122
|
+
| --- | -------- |
|
|
123
|
+
| `https://<DOMAIN>/` | 200, HTTPS, valid cert |
|
|
124
|
+
| `https://<DOMAIN>/manifest.webmanifest` | 200, `Content-Type: application/manifest+json` |
|
|
125
|
+
| `https://<DOMAIN>/icons/icon-512.png` | 200, `image/png` |
|
|
126
|
+
| `https://<DOMAIN>/.well-known/assetlinks.json` | 200, `application/json` (after the keystore step) |
|
|
127
|
+
| `https://<DOMAIN>/android.keystore` | **404** — the keystore must never be published |
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
for u in / /manifest.webmanifest /icons/icon-512.png /.well-known/assetlinks.json; do
|
|
131
|
+
printf '%s ' "$u"; curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "https://<DOMAIN>$u"
|
|
132
|
+
done
|
|
133
|
+
curl -s -o /dev/null -w 'keystore %{http_code} (want 404)\n' "https://<DOMAIN>/android.keystore"
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Two failures are worth calling out because they look like host bugs and are not:
|
|
137
|
+
|
|
138
|
+
- **`.well-known/` 404s** while everything else works — the host is stripping
|
|
139
|
+
dotfolders. Fix per [`references/existing-hosts.md`](references/existing-hosts.md);
|
|
140
|
+
do not work around it by moving the file, the path is fixed by the TWA spec.
|
|
141
|
+
- **The manifest serves as `text/plain`** — some hosts have no mapping for
|
|
142
|
+
`.webmanifest`. Add the MIME type, or serve it as `manifest.json` and update
|
|
143
|
+
the `<link rel="manifest">` and `webManifestUrl` to match.
|
|
144
|
+
|
|
145
|
+
## 5. Hosting at a subpath
|
|
146
|
+
|
|
147
|
+
If the app is served from `https://<DOMAIN>/<path>/` rather than the origin
|
|
148
|
+
root, two things change and both break silently:
|
|
149
|
+
|
|
150
|
+
- `start_url` and `scope` in the web manifest must be `/<path>/`, not `/`.
|
|
151
|
+
- `assetlinks.json` still has to sit at the **origin root**
|
|
152
|
+
(`https://<DOMAIN>/.well-known/assetlinks.json`) — a subpath copy is ignored.
|
|
153
|
+
If the developer does not control the origin root, they cannot ship a TWA from
|
|
154
|
+
that origin. Say so plainly and offer Route A as the alternative.
|
|
155
|
+
|
|
156
|
+
`base: './'` is already set in the scaffolded `vite.config.*`, so the JS/CSS
|
|
157
|
+
bundles themselves are fine at any path — it is only these two that need care.
|
|
158
|
+
|
|
159
|
+
## 6. Redeploy vs rebuild
|
|
160
|
+
|
|
161
|
+
Once the APK exists, keep this distinction straight — it saves a Store round
|
|
162
|
+
trip:
|
|
163
|
+
|
|
164
|
+
- **Web-only change** (app logic, styling, manifest text, icons, asset links) →
|
|
165
|
+
republish `<DOMAIN>`. The installed TWA picks it up on next launch.
|
|
166
|
+
- **Native change** (package id, app name, launcher icon, version, app mode,
|
|
167
|
+
signing) → rebuild the APK and re-upload to the Store.
|
|
168
|
+
|
|
169
|
+
## Reference Files
|
|
170
|
+
|
|
171
|
+
| File | Load when |
|
|
172
|
+
| ---- | --------- |
|
|
173
|
+
| [`references/vercel.md`](references/vercel.md) | Route A — full Vercel deploy, auth, aliases, redeploys |
|
|
174
|
+
| [`references/existing-hosts.md`](references/existing-hosts.md) | Route B — per-host publish recipes and their gotchas |
|
|
175
|
+
|
|
176
|
+
Packaging the hosted app into a signed Quest APK is the `iwsdk-pwa-packaging`
|
|
177
|
+
skill; this skill only gets it online.
|