@iwsdk/create 1.1.0 → 1.2.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/README.md +68 -16
- package/dist/cli.js +7917 -3404
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-compose-scene/SKILL.md +3 -2
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-debug/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-dev/references/api-reference.md +8 -1
- package/dist/guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/iterate.md +16 -7
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/planner.md +9 -5
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-grab/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/SKILL.md +3 -1
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
- package/dist/guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-physics/references/workflows.md +9 -3
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-pwa-packaging/SKILL.md +13 -1
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-ray/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-ui/SKILL.md +17 -7
- package/dist/guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/guidance/{claude → files}/.claude/agents/iwsdk-project-code-reviewer.md +1 -0
- package/dist/guidance/{claude → files}/.claude/rules/assets-and-manifest.md +3 -0
- package/dist/guidance/{claude → files}/.claude/rules/ecs-api.md +1 -0
- package/dist/guidance/{claude → files}/.claude/rules/scene-json.md +1 -0
- package/dist/guidance/{claude → files}/.claude/rules/uikitml.md +1 -0
- package/dist/guidance/{claude → files}/.claude/settings.json +9 -3
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-compose-scene/SKILL.md +3 -2
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-debug/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-dev/references/api-reference.md +8 -1
- package/dist/guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/iterate.md +16 -7
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/planner.md +9 -5
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-grab/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/SKILL.md +3 -1
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
- package/dist/guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-physics/references/workflows.md +9 -3
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-pwa-packaging/SKILL.md +13 -1
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-ray/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-ui/SKILL.md +17 -7
- package/dist/guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/assets-and-manifest.mdc +3 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/ecs-api.mdc +1 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/scene-json.mdc +1 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/uikitml.mdc +1 -0
- package/dist/guidance/{copilot → files}/.github/instructions/assets-and-manifest.instructions.md +2 -1
- package/dist/guidance/{copilot → files}/.github/instructions/ecs-api.instructions.md +1 -0
- package/dist/guidance/{copilot → files}/.github/instructions/scene-json.instructions.md +1 -0
- package/dist/guidance/{copilot → files}/.github/instructions/uikitml.instructions.md +1 -0
- package/dist/guidance/{common → files}/AGENTS.md +107 -27
- package/dist/guidance/{scoped-agents → files}/public/scenes/AGENTS.md +2 -0
- package/dist/guidance/{scoped-agents → files}/public/ui/AGENTS.md +2 -0
- package/dist/guidance/{scoped-agents → files}/src/AGENTS.md +2 -0
- package/dist/guidance/manifest.json +954 -0
- package/dist/template/common/.codex/config.toml +2 -0
- package/package.json +5 -5
- package/scripts/verify-release-ready.mjs +1 -2
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/agents/openai.yaml +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/vercel.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/component-reference.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/agents/openai.yaml +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/vercel.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/component-reference.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
- /package/dist/guidance/{claude → files}/CLAUDE.md +0 -0
- /package/dist/{guidance/codex → template/common-js}/.codex/config.toml +0 -0
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Build Step
|
|
2
|
+
|
|
3
|
+
`scripts/write-service-worker.mjs` (copied from
|
|
4
|
+
`assets/write-service-worker.mjs.template`) runs after `vite build`, once every
|
|
5
|
+
output file — `public/` included — is in `dist/`. It hashes each file, sorts it
|
|
6
|
+
into a list, names the release, and writes `dist/sw.js` from
|
|
7
|
+
`scripts/sw.js.template`.
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"scripts": {
|
|
12
|
+
"build": "vite build && node scripts/write-service-worker.mjs dist scripts/sw.js.template"
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
It prints `sw.js: release <name>, <n> files, <m> on request`. Read that line
|
|
18
|
+
after every change to the rules.
|
|
19
|
+
|
|
20
|
+
## Rewrite the rules for the app
|
|
21
|
+
|
|
22
|
+
- **`LEFT_OUT`** — never listed. Keep the worker itself, source maps, crawler
|
|
23
|
+
and link-preview files, and `AGENTS.md`; add anything nothing requests.
|
|
24
|
+
- **`ON_REQUEST`** — listed with its hash, but copied only once the page fetches
|
|
25
|
+
it. Use it for files only some users need: copying them for everyone costs
|
|
26
|
+
every user for the benefit of a few. The kit's two rules
|
|
27
|
+
(`fonts/(ja|ko|zh)-`, `levels/extra-`) are examples; replace them.
|
|
28
|
+
|
|
29
|
+
## Three details that matter
|
|
30
|
+
|
|
31
|
+
- The paths are sorted before hashing, so the same output always gives the same
|
|
32
|
+
release name, and an unchanged build writes a byte-identical `sw.js`, which
|
|
33
|
+
browsers ignore.
|
|
34
|
+
- The placeholders are replaced through functions, because a replacement string
|
|
35
|
+
would read `$&` in a file name as a pattern.
|
|
36
|
+
- The script must run after every file exists: a file written later is missing
|
|
37
|
+
from the list, so it is never kept. That is why it runs after `vite build`
|
|
38
|
+
rather than from a plugin's `closeBundle` hook.
|
|
39
|
+
|
|
40
|
+
## Identify files by hash
|
|
41
|
+
|
|
42
|
+
Decide everything by the SHA-256 of a file's bytes, never by its name, date, or
|
|
43
|
+
version number. The one hash answers three questions: did the file change since
|
|
44
|
+
the last release, is a copy already on the device, and is the copy just
|
|
45
|
+
downloaded the right one.
|
|
46
|
+
|
|
47
|
+
| Signal | Decide by it? | Why |
|
|
48
|
+
| --- | --- | --- |
|
|
49
|
+
| SHA-256 of the bytes, computed at build | yes | the same bytes give the same hash on any machine |
|
|
50
|
+
| Hashed file names (`index-3f9a2c.js`) | only for Vite's own output | files copied from `public/` keep their names when their content changes |
|
|
51
|
+
| Modification time | no | a fresh checkout or a CI build gives every file a new time |
|
|
52
|
+
| `ETag` or `Last-Modified` | no | each server or CDN edge computes its own |
|
|
53
|
+
| One version number for the whole app | only as a label | a new number makes every file look changed, so every user downloads everything again |
|
|
54
|
+
|
|
55
|
+
## Duplicate files
|
|
56
|
+
|
|
57
|
+
Two paths with identical bytes share a hash but are stored twice, because the
|
|
58
|
+
Cache API keys entries by URL. To find them, group the list by hash inside
|
|
59
|
+
`writeServiceWorker()` (`Object.groupBy` needs Node.js 21 or later):
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
const byHash = Object.groupBy(Object.entries(files), ([, hash]) => hash);
|
|
63
|
+
for (const group of Object.values(byHash)) {
|
|
64
|
+
if (group.length > 1)
|
|
65
|
+
console.warn('same bytes:', group.map(([path]) => path).join(', '));
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
One duplicate is built in: the page loads `/`, but the list names `index.html`,
|
|
70
|
+
so a first visit fetches the entry page twice under two URLs. It is usually a
|
|
71
|
+
few kilobytes; list the entry page under its own URL if that matters.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Page Side
|
|
2
|
+
|
|
3
|
+
`src/offline.ts` (copied from `assets/offline.ts.template`) decides two moments:
|
|
4
|
+
when the copy is made, and when a new release may take over. It exports three
|
|
5
|
+
functions:
|
|
6
|
+
|
|
7
|
+
- **`startOffline(isIdle)`** — call first thing at startup. If a release
|
|
8
|
+
finished installing on an earlier visit, it takes over before anything
|
|
9
|
+
starts; otherwise it watches for one.
|
|
10
|
+
- **`keepOfflineCopy(isIdle)`** — call once the first screen is up. It registers
|
|
11
|
+
`./sw.js`, asks the browser to keep the copy with `navigator.storage.persist()`,
|
|
12
|
+
and reports what the page fetched before the worker existed.
|
|
13
|
+
- **`checkIdle()`** — call whenever the app becomes idle, such as when an XR
|
|
14
|
+
session ends. A release that installed while the app was busy takes over
|
|
15
|
+
then, instead of waiting for the next load.
|
|
16
|
+
|
|
17
|
+
In a JavaScript project, save it as `src/offline.js` and delete the type
|
|
18
|
+
annotations. In a TypeScript project it must be `.ts`: the scaffold's
|
|
19
|
+
`tsconfig.json` has no `allowJs`, so importing a `.js` module fails
|
|
20
|
+
`npm run typecheck`.
|
|
21
|
+
|
|
22
|
+
## Wiring in `src/index.ts`
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { VisibilityState, World } from '@iwsdk/core';
|
|
26
|
+
import projectOptions from 'virtual:iwsdk-project';
|
|
27
|
+
import { checkIdle, keepOfflineCopy, startOffline } from './offline.js';
|
|
28
|
+
|
|
29
|
+
let world: World | undefined;
|
|
30
|
+
const isIdle = () =>
|
|
31
|
+
world?.visibilityState.peek() === VisibilityState.NonImmersive;
|
|
32
|
+
startOffline(isIdle);
|
|
33
|
+
|
|
34
|
+
World.create(
|
|
35
|
+
document.getElementById('scene-container') as HTMLDivElement,
|
|
36
|
+
projectOptions,
|
|
37
|
+
).then((created) => {
|
|
38
|
+
world = created;
|
|
39
|
+
// ... register your systems ...
|
|
40
|
+
keepOfflineCopy(isIdle);
|
|
41
|
+
created.visibilityState.subscribe(() => checkIdle());
|
|
42
|
+
});
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Why each part is there
|
|
46
|
+
|
|
47
|
+
- **Register after the first screen, not at startup.** Registered at startup,
|
|
48
|
+
the worker downloads the release while the page is still downloading it, so
|
|
49
|
+
every file comes down twice. Registered later, the worker takes each file from
|
|
50
|
+
the HTTP cache instead.
|
|
51
|
+
- **Report what came before the worker.** Files the page fetched before the
|
|
52
|
+
worker existed never passed through it. The buffered `PerformanceObserver`
|
|
53
|
+
reports them, and the worker keeps the optional and pinned ones among them.
|
|
54
|
+
The browser buffers 250 resource entries by default; if the first load fetches
|
|
55
|
+
more, raise the limit early with `performance.setResourceTimingBufferSize()`.
|
|
56
|
+
- **Define idle for the app.** `isIdle()` must be `false` whenever a reload
|
|
57
|
+
could lose work or interrupt a session. No XR session is the IWSDK baseline;
|
|
58
|
+
add the app's own state, such as an unsaved edit or a game in progress, and
|
|
59
|
+
call `checkIdle()` when that state ends. When `isIdle()` is `true` and a new
|
|
60
|
+
release has installed, the page sends `'take-over'`, listens for
|
|
61
|
+
`controllerchange`, and reloads into the new release. The worker ignores the
|
|
62
|
+
request while another page of the app is open, so asking again later is safe.
|
|
63
|
+
- **Catch an install already under way.** The browser checks `sw.js` as the page
|
|
64
|
+
navigates, so an update can be installing before the page's script runs, its
|
|
65
|
+
`updatefound` already gone. `watch()` follows `registration.waiting`,
|
|
66
|
+
`registration.installing`, and the next `updatefound`, so none is missed.
|
|
67
|
+
- **Mirror the connection.** `navigator.onLine` and the `online` and `offline`
|
|
68
|
+
events say whether the device has a network, not whether the server answers.
|
|
69
|
+
Use them to disable or explain features that need a connection, and still
|
|
70
|
+
handle failed requests.
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Service Worker
|
|
2
|
+
|
|
3
|
+
`scripts/sw.js.template` (copied from `assets/sw.js.template`) has three
|
|
4
|
+
placeholders — `RELEASE`, `FILES`, and `ON_REQUEST` — that the build step fills
|
|
5
|
+
in. It is plain JavaScript with no imports, so it is copied, not bundled. Install
|
|
6
|
+
copies the release, activate removes older releases, and fetch answers from the
|
|
7
|
+
copy.
|
|
8
|
+
|
|
9
|
+
## Request routing
|
|
10
|
+
|
|
11
|
+
| Request | Answered from |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| Anything but a GET | the network, untouched |
|
|
14
|
+
| A pinned third-party URL | its long-lived cache; else the network, and kept |
|
|
15
|
+
| A path in `FILES` | the release cache; the network only if the browser evicted it |
|
|
16
|
+
| A path in `ON_REQUEST` | the release cache once kept; until then the network, kept if its hash matches |
|
|
17
|
+
| A navigation to a folder, such as the site root | that folder's `index.html` from the release cache |
|
|
18
|
+
| Anything else | the network, untouched |
|
|
19
|
+
|
|
20
|
+
## What to change
|
|
21
|
+
|
|
22
|
+
- **`PREFIX`, `KEPT`, `HASH`** — rename for the app. `KEPT` must not start with
|
|
23
|
+
`PREFIX`, or the next activation deletes it.
|
|
24
|
+
- **`PINNED`** — covers IWSDK's controller models, the three.js decoders, and
|
|
25
|
+
the starter's stock models on jsDelivr. Match `three@` to the project's
|
|
26
|
+
three.js revision and `example-assets@` to `src/assets.ts`, and delete the
|
|
27
|
+
stock-model path if the app mirrors those files or never loads them. If the
|
|
28
|
+
app fetches nothing from other origins, delete `PINNED`, `PAIRED`,
|
|
29
|
+
`thirdParty()`, `keepPinned()`, and `keepPair()`.
|
|
30
|
+
|
|
31
|
+
Third-party files often come in families. IWSDK's controller models come as
|
|
32
|
+
`left.glb` and `right.glb` in the same profile folder, so `PAIRED` keeps the
|
|
33
|
+
other hand's model whenever one is kept: a user who only ever used one
|
|
34
|
+
controller online still has both offline. Add a rule like it for any other
|
|
35
|
+
family the app fetches piece by piece.
|
|
36
|
+
|
|
37
|
+
## Behaviour to keep
|
|
38
|
+
|
|
39
|
+
- **Cache-first, with no revalidation.** A page loaded from the copy is exactly
|
|
40
|
+
its release, and a new release arrives only through `sw.js`.
|
|
41
|
+
- **Query strings are ignored**, so a start URL such as `/?source=pwa` gets the
|
|
42
|
+
cached `index.html`.
|
|
43
|
+
- **No `skipWaiting()` of its own.** The worker calls it only on the page's
|
|
44
|
+
`'take-over'` message; the page decides when a release takes over.
|
|
45
|
+
- **A take-over needs the asking page to be alone.** `skipWaiting()` moves every
|
|
46
|
+
open page of the scope onto the new release, and activation deletes the old
|
|
47
|
+
release's cache under them: a second tab in the middle of an XR session would
|
|
48
|
+
load the new release's files, or none offline. So the worker grants
|
|
49
|
+
`'take-over'` only when one window of the scope is open; otherwise the release
|
|
50
|
+
waits until every page has closed, and the browser activates it then.
|
|
51
|
+
- **Only CORS responses are kept.** A `no-cors` request returns an opaque
|
|
52
|
+
response with status `0` and an unreadable body, which cannot be checked.
|
|
53
|
+
|
|
54
|
+
## Where the hash is compared
|
|
55
|
+
|
|
56
|
+
- **At build.** The release is named by a hash of its whole file list, so it
|
|
57
|
+
changes exactly when a listed file changes.
|
|
58
|
+
- **At install, file by file.** The worker looks in this release's own cache
|
|
59
|
+
first (an interrupted install resumes), then in earlier releases' caches, then
|
|
60
|
+
in the HTTP cache, and only then asks the server. Each cached copy carries its
|
|
61
|
+
hash in an `x-content-sha256` header, so an unchanged file is copied across,
|
|
62
|
+
never downloaded.
|
|
63
|
+
- **After every download.** The bytes are hashed before they are cached. A
|
|
64
|
+
mismatch is asked for again with `cache: 'no-cache'`, and a second mismatch
|
|
65
|
+
fails the install, which the browser retries on a later visit. This catches
|
|
66
|
+
stale CDN edges and a deploy that is still spreading.
|
|
67
|
+
- **On a first visit.** The page downloads its files before the worker exists,
|
|
68
|
+
and the worker takes them from the HTTP cache, so nothing crosses the wire
|
|
69
|
+
twice.
|
|
70
|
+
- **For optional files.** The same check runs when one is first fetched: a
|
|
71
|
+
stale copy is served that once and never kept.
|
|
72
|
+
- **For third-party files.** They have no hash in the list. The pinned URL is
|
|
73
|
+
their identity, and each is kept once per device.
|
|
74
|
+
|
|
75
|
+
## Updates
|
|
76
|
+
|
|
77
|
+
A new release installs beside the old one and waits. The page decides when it
|
|
78
|
+
takes over: at once if `isIdle()` is `true`, when the app next calls
|
|
79
|
+
`checkIdle()` while idle, or otherwise at the next load, before the app builds
|
|
80
|
+
anything — each time only if no other page of the app is open. Installing reuses every unchanged file from the old
|
|
81
|
+
release's cache by its hash, so an update downloads only what changed. Optional
|
|
82
|
+
files the old release kept come across while their hash is unchanged, and the
|
|
83
|
+
third-party cache is never touched. After `'take-over'`, activation deletes the
|
|
84
|
+
older release caches and claims the page, which sees `controllerchange` and
|
|
85
|
+
reloads from the new copy.
|
|
86
|
+
|
|
87
|
+
## Vercel headers
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"headers": [
|
|
92
|
+
{
|
|
93
|
+
"source": "/sw.js",
|
|
94
|
+
"headers": [{ "key": "Cache-Control", "value": "no-cache" }]
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
"source": "/assets/(.*)",
|
|
98
|
+
"headers": [
|
|
99
|
+
{
|
|
100
|
+
"key": "Cache-Control",
|
|
101
|
+
"value": "public, max-age=31536000, immutable"
|
|
102
|
+
}
|
|
103
|
+
]
|
|
104
|
+
}
|
|
105
|
+
]
|
|
106
|
+
}
|
|
107
|
+
```
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Testing the Offline Copy
|
|
2
|
+
|
|
3
|
+
Six checks prove the design. Each is about what crosses the wire, so the test
|
|
4
|
+
watches the wire.
|
|
5
|
+
|
|
6
|
+
| # | Check | Pass when |
|
|
7
|
+
| - | ----- | --------- |
|
|
8
|
+
| 1 | First visit | the release cache holds every listed file; no file was sent in full twice; no optional file nobody asked for was downloaded; optional and pinned files fetched before the worker existed are kept |
|
|
9
|
+
| 2 | Reload | the server is asked for nothing but `sw.js` |
|
|
10
|
+
| 3 | Offline | with the network off, a reload starts the app and kept files are served; an optional file never fetched online is missing, as it should be |
|
|
11
|
+
| 4 | Update while idle | after one file changes, only that file is downloaded; the new release takes over; the old release cache is gone; kept optional files came across |
|
|
12
|
+
| 5 | Update mid-session | the page is not reloaded during the session; when it ends, the new release takes over |
|
|
13
|
+
| 6 | Two pages open | an update while a second page of the app is open takes over neither page; once only one remains, the next idle moment or load takes it |
|
|
14
|
+
|
|
15
|
+
## Harness
|
|
16
|
+
|
|
17
|
+
- **A logging server.** Serve the built `dist/` from a small server that logs
|
|
18
|
+
every request and answers revalidations with ETags and `304`, as a real host
|
|
19
|
+
does. Count only full `200` responses per path: a path sent twice is a
|
|
20
|
+
duplicate download.
|
|
21
|
+
- **No request interception.** Playwright turns the HTTP cache off whenever a
|
|
22
|
+
route is registered, and the first copy is made from that cache.
|
|
23
|
+
- **A persistent browser profile** (`launchPersistentContext`). It keeps the
|
|
24
|
+
HTTP cache on disk, as on a real device; an in-memory cache may refuse a large
|
|
25
|
+
file.
|
|
26
|
+
- **Polling loops.** Wait by calling `page.evaluate()` in a loop.
|
|
27
|
+
`page.waitForFunction()` does not wait for an async predicate, because a
|
|
28
|
+
promise counts as truthy.
|
|
29
|
+
- **An offline switch.** `context.setOffline(true)` takes the context offline
|
|
30
|
+
for check 3.
|
|
31
|
+
- **An XR session for check 5.** In desktop Chromium the injected IWER emulator
|
|
32
|
+
provides one: call `world.launchXR()` and wait until `world.visibilityState`
|
|
33
|
+
leaves `'non-immersive'`, so `isIdle()` is `false`.
|
|
34
|
+
|
|
35
|
+
Playwright attaches to every service worker, and that can stall activation after
|
|
36
|
+
`skipWaiting()` for over a minute, in some runs and not in others. If checks 4
|
|
37
|
+
or 5 hang on the take-over, drive them over the Chrome DevTools Protocol with
|
|
38
|
+
only the page attached, or by hand.
|
|
39
|
+
|
|
40
|
+
## On the headset
|
|
41
|
+
|
|
42
|
+
Test a production build: `npm run dev` serves no `sw.js`. Build, serve `dist/`
|
|
43
|
+
over plain HTTP on a local port, and forward it so that
|
|
44
|
+
`http://localhost:<port>` counts as a secure context in Meta Quest Browser:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm run build
|
|
48
|
+
python3 -m http.server 4173 --bind 127.0.0.1 --directory dist
|
|
49
|
+
adb reverse tcp:4173 tcp:4173 # then open http://localhost:4173 on the headset
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Not `npx vite preview`: the IWSDK Vite plugin serves it over HTTPS with a
|
|
53
|
+
self-signed certificate, and Quest Browser refuses to register a service worker
|
|
54
|
+
from a page with a certificate error.
|
|
55
|
+
|
|
56
|
+
Clear the origin's storage between runs, for example with the DevTools
|
|
57
|
+
Protocol's `Storage.clearDataForOrigin`, or the site settings in the browser.
|
|
@@ -103,3 +103,4 @@ authored render cover deliberate framing.
|
|
|
103
103
|
Make at most one focused correction, then replay the same observation. Stop
|
|
104
104
|
when the requested bodies, collisions, and final state are evidenced. Resume
|
|
105
105
|
ECS time and leave the app in a stable state.
|
|
106
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=24a1d1e5a61472ec045759f5e385de1843df34b6e43613dcd6b591c439ec69f1 name=iwsdk-physics (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/tuning-and-config.md
RENAMED
|
@@ -45,6 +45,7 @@ The project manifest accepts execution, frequency, and interpolation options:
|
|
|
45
45
|
- `useWorker` defaults to `true`. Set it to `false` to run the same runtime and message protocol on the main thread.
|
|
46
46
|
- `updateFrequency` defaults to 60 Hz and is capped at 240 Hz.
|
|
47
47
|
- `interpolation` defaults to `true` and smooths rendered transforms between fixed physics snapshots.
|
|
48
|
+
- `applyScale` defaults to `false`. `Auto` shapes and mesh-derived `ConvexHull`/`TriMesh` shapes always use the object's world scale. Shapes with explicit `dimensions` ignore it unless `applyScale` is `true`; a scaled object with explicit dimensions logs a one-time warning. Prefer `applyScale: true` in new projects and author dimensions in the object's unscaled units.
|
|
48
49
|
|
|
49
50
|
The system also accepts a reactive `gravity` config (defaults to Earth gravity):
|
|
50
51
|
|
package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-physics/references/workflows.md
RENAMED
|
@@ -70,7 +70,10 @@ envEntity.addComponent(PhysicsBody, { state: PhysicsState.Static });
|
|
|
70
70
|
|
|
71
71
|
### Creating a Kinematic Moving Platform
|
|
72
72
|
|
|
73
|
-
Kinematic bodies
|
|
73
|
+
Kinematic bodies follow their Object3D: move it from a system and the body sweeps
|
|
74
|
+
there over the next physics steps, pushing dynamic objects and carrying anything
|
|
75
|
+
resting on it. When the Object3D stops, the body stops with it. Don't apply
|
|
76
|
+
`PhysicsManipulation` to a kinematic body; it is ignored with a warning.
|
|
74
77
|
|
|
75
78
|
```typescript
|
|
76
79
|
// Setup
|
|
@@ -110,7 +113,10 @@ physics.setBodyTransform(entity, {
|
|
|
110
113
|
```
|
|
111
114
|
|
|
112
115
|
Velocity is cleared by default. Pass `{ resetVelocity: false }` only when a teleport
|
|
113
|
-
must preserve motion.
|
|
116
|
+
must preserve motion. The pose is relative to the entity's parent, like
|
|
117
|
+
`object3D.position`; pass `{ space: 'world' }` for a world-space pose. Physics
|
|
118
|
+
simulates in world space, so bodies may live under a moved level root or another
|
|
119
|
+
entity. `gravityFactor`, `linearDamping`, and `angularDamping` can be
|
|
114
120
|
changed reactively with `entity.setValue`; changing motion state or shape requires
|
|
115
121
|
deliberate body lifecycle handling.
|
|
116
122
|
|
|
@@ -140,7 +146,7 @@ entity.addComponent(DistanceGrabbable, {
|
|
|
140
146
|
});
|
|
141
147
|
```
|
|
142
148
|
|
|
143
|
-
When grabbed, the `
|
|
149
|
+
When grabbed, the `PhysicsSystem` makes a dynamic body kinematic and drives it toward the hand pose, so it pushes other bodies without being knocked out of the hand. A pose jump faster than a hand can move, such as an emulator controller teleport, moves the held body without sweeping it through its neighbours. On release, the body is dynamic again and leaves with the hand's recent velocity, smoothed over about 50 ms and capped at 10 m/s. Note: near-field grabs do not add `Hovered`/`Pressed` tags — assert grab behavior with ECS snapshot/diff, not tag queries.
|
|
144
150
|
|
|
145
151
|
### Reading Velocity for Game Logic
|
|
146
152
|
|
|
@@ -80,6 +80,12 @@ it on the headset after sideloading (step 4).
|
|
|
80
80
|
`index.html` ships `<link rel="icon" href="data:," />` and no manifest link, so
|
|
81
81
|
the app is not installable until step 3 adds them.
|
|
82
82
|
|
|
83
|
+
**Optional: launch offline.** The TWA loads `<DOMAIN>` over the network, so with
|
|
84
|
+
no connection an installed app shows an error page instead of the app. If it
|
|
85
|
+
must launch offline, add an offline copy with the `iwsdk-offline` skill before
|
|
86
|
+
packaging: one online launch then keeps the release on the device. Keep the
|
|
87
|
+
manifest's `start_url` and `scope` inside the service worker's scope.
|
|
88
|
+
|
|
83
89
|
Then confirm the app itself is sound before wrapping it — `npm run --if-present typecheck`,
|
|
84
90
|
and `npm run build` producing a `dist/` you have actually loaded. Packaging a
|
|
85
91
|
broken build wastes a full round trip through hosting, signing, and upload.
|
|
@@ -191,6 +197,10 @@ retry the identical command. Tool download, auth, and flag reference:
|
|
|
191
197
|
| App logic, assets, styling, manifest text, icons, asset links | republish `<DOMAIN>`; installed TWA picks it up next launch |
|
|
192
198
|
| Package id, app name, launcher icon, version, **app mode**, signing | rebuild the APK and re-upload |
|
|
193
199
|
|
|
200
|
+
With an offline copy (`iwsdk-offline`), a republished release installs in the
|
|
201
|
+
background during a launch and takes over when the app is idle, or on the
|
|
202
|
+
launch after that.
|
|
203
|
+
|
|
194
204
|
## Security
|
|
195
205
|
|
|
196
206
|
The keystore and the app secret never go near `public/` or `dist/`. After every
|
|
@@ -213,6 +223,8 @@ updated — only replaced by a new Store entry.
|
|
|
213
223
|
| [`references/store-upload.md`](references/store-upload.md) | Step 5 — `ovr-platform-util`, auth, channels, the DDA blocker |
|
|
214
224
|
| [`references/troubleshooting.md`](references/troubleshooting.md) | Anything installed but misbehaving — stuck loading, URL bar, will-not-launch |
|
|
215
225
|
|
|
216
|
-
Getting the app online is the `iwsdk-hosting` skill
|
|
226
|
+
Getting the app online is the `iwsdk-hosting` skill, and keeping it working
|
|
227
|
+
offline is `iwsdk-offline`. Building the app itself is
|
|
217
228
|
`iwsdk-planner` and the other `iwsdk-*` skills — do not re-derive IWSDK
|
|
218
229
|
patterns here.
|
|
230
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=2fbb9b9e9245162fa8cdb51e0a1396dde89b3d459ad5bcc29b45b92ade7a0022 name=iwsdk-pwa-packaging (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -34,7 +34,7 @@ it is served at `/manifest.webmanifest` with no further wiring.
|
|
|
34
34
|
| Field | Why it matters here |
|
|
35
35
|
| ----- | ------------------- |
|
|
36
36
|
| `name` / `short_name` | `short_name` is the launcher label; keep it under ~12 characters or it truncates |
|
|
37
|
-
| `start_url` / `scope` | must match the hosting path — `/` at an origin root, `/<path>/` on a subpath deployment |
|
|
37
|
+
| `start_url` / `scope` | must match the hosting path — `/` at an origin root, `/<path>/` on a subpath deployment; with an offline copy (`iwsdk-offline`), both must also sit inside the service worker's scope |
|
|
38
38
|
| `display` | `standalone` for both modes; `browser` forces a URL bar |
|
|
39
39
|
| `background_color` | painted before first frame — match the app's clear color or launch flashes white |
|
|
40
40
|
| `theme_color` | colors the custom tab bar on a 2D panel; add `theme_color_dark` if the app is dark-first |
|
|
@@ -10,6 +10,8 @@ symptoms, so start there.
|
|
|
10
10
|
| Opens with a browser URL bar | `horizonOSAppMode: "2D"` on an immersive app | [App mode](#app-mode-failures) |
|
|
11
11
|
| Opens flat, no URL bar, never enters VR | auto-enter code missing or not firing | [App mode](#app-mode-failures) |
|
|
12
12
|
| Blank / white / error page | the origin is unreachable from the device | [Origin](#origin-failures) |
|
|
13
|
+
| Error page only when the headset is offline | no offline copy, or the app never launched online | [Offline](#offline-failures) |
|
|
14
|
+
| Old version after a web redeploy | an offline copy waiting for an idle moment or the next launch | [Offline](#offline-failures) |
|
|
13
15
|
|
|
14
16
|
Before diagnosing, establish which layer is wrong. A **web** bug is fixed by
|
|
15
17
|
republishing `<DOMAIN>`; a **native** bug needs a new APK and a new upload.
|
|
@@ -116,6 +118,34 @@ to `/<path>/` and republish. The scaffolded `base: './'` handles the bundle
|
|
|
116
118
|
paths already, so if bundles load and only `public/` assets 404, look for a
|
|
117
119
|
publish that missed those files.
|
|
118
120
|
|
|
121
|
+
## Offline failures
|
|
122
|
+
|
|
123
|
+
These apply only when the site keeps an offline copy (`iwsdk-offline`).
|
|
124
|
+
|
|
125
|
+
### Error page only when the headset is offline
|
|
126
|
+
|
|
127
|
+
The device has no copy to serve. Usually one of:
|
|
128
|
+
|
|
129
|
+
- **No offline copy** — the site registers no service worker. Add one with
|
|
130
|
+
`iwsdk-offline`.
|
|
131
|
+
- **The app never launched online** since the copy was added. The copy is made
|
|
132
|
+
on the first online launch.
|
|
133
|
+
- **`start_url` or `scope` sits outside the worker's scope**, so the launch
|
|
134
|
+
misses the copy. Serve `sw.js` from the root of that scope.
|
|
135
|
+
|
|
136
|
+
Confirm the worker is live and uncached:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
curl -sI https://<DOMAIN>/sw.js | grep -iE '^(HTTP|cache-control)' # want 200, no-cache
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Old version after a web redeploy
|
|
143
|
+
|
|
144
|
+
Expected for one launch: the new release installs in the background during a
|
|
145
|
+
launch and takes over when the app is idle, or on the launch after that. If it
|
|
146
|
+
never arrives, `sw.js` is being cached — serve it with `Cache-Control: no-cache`
|
|
147
|
+
and purge the CDN.
|
|
148
|
+
|
|
119
149
|
## Packaging failures
|
|
120
150
|
|
|
121
151
|
### bubblewrap hangs or exits without doing anything
|
|
@@ -67,3 +67,4 @@ When the request names an artifact path, save it directly with
|
|
|
67
67
|
context and then add a copy step.
|
|
68
68
|
Stop when the real input and resulting named state are proven, leaving all
|
|
69
69
|
buttons released.
|
|
70
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=ec23dce5226ca91367042de7907fb3664c055a1ceb737fede2fd6710eab1f37f name=iwsdk-ray (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -186,8 +186,8 @@ views independently when both modes matter.
|
|
|
186
186
|
## Verify with a bounded loop
|
|
187
187
|
|
|
188
188
|
Typecheck after the complete first slice, then start or reuse one managed
|
|
189
|
-
session. If no command-ready session exists, run `npx @iwsdk/cli dev up
|
|
190
|
-
|
|
189
|
+
session. If no command-ready session exists, run `npx @iwsdk/cli dev up` once,
|
|
190
|
+
with the `--ai-mode` that AGENTS.md's session rule picks. Do not call `dev --help`, separately call `dev open`, restart a healthy
|
|
191
191
|
session, start a second browser, or build a custom UIKit renderer.
|
|
192
192
|
|
|
193
193
|
1. Run `npx @iwsdk/cli ui assets --raw` once to confirm registration.
|
|
@@ -256,17 +256,26 @@ it.
|
|
|
256
256
|
|
|
257
257
|
When the request asks for a poke (near touch) on a control, press it with the
|
|
258
258
|
emulated hand's index fingertip by its element ID. The panel entity needs
|
|
259
|
-
`PokeInteractable
|
|
259
|
+
`PokeInteractable`. Its `hand` field (`"both"`, the default, `"left"` or
|
|
260
|
+
`"right"`) limits which hand can poke it, for example a wrist menu that only
|
|
261
|
+
the other hand should press:
|
|
260
262
|
|
|
261
263
|
```bash
|
|
262
264
|
npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
|
|
263
265
|
npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Btn_Action","press":{}}]}' --timeout 45000
|
|
264
266
|
```
|
|
265
267
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
268
|
+
A press result reports contact, not a click: a `presses[0].contactMs` of 800 or
|
|
269
|
+
less does not prove the control clicked, because the fingertip can touch the
|
|
270
|
+
panel or a neighbouring control instead. Verify the click by the state it
|
|
271
|
+
changes, with `ui inspect` on the control or a query of the app state it
|
|
272
|
+
drives, and press once more if nothing changed. A contact of more than 800 ms
|
|
273
|
+
never clicks. A slow headless frame can hold the touch that long. So can a
|
|
274
|
+
press on a control out of reach: the body walks to it during the press (a
|
|
275
|
+
contact of seconds). Walk to such a control in a step of its own before the
|
|
276
|
+
press:
|
|
277
|
+
`"steps":[{"body":{"stepTo":"Btn_Action"}},{"target":"Btn_Action","press":{}}]`.
|
|
278
|
+
`xr list-targets` lists the element IDs that can be pressed.
|
|
270
279
|
|
|
271
280
|
The commands in this section are the supported path. Do not call broad
|
|
272
281
|
`iwsdk`, `ui`, `browser`, `ecs`, or `xr` help. If a shown command fails, use its
|
|
@@ -323,3 +332,4 @@ The final visual check must confirm:
|
|
|
323
332
|
Finish with a passing typecheck and production build, no UIKit parser/resource
|
|
324
333
|
errors, and concise runtime evidence. Remove temporary preview files or camera
|
|
325
334
|
workarounds that are not deliverables.
|
|
335
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=9b79caeeedded4cb53e69688c7e5006daa1187c951a333ef06cbdb3063f062a2 name=iwsdk-ui (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-upgrade
|
|
3
|
+
description: Upgrade an IWSDK app to a newer IWSDK release and prove it still works. Use when the user asks to upgrade, update or bump IWSDK or any @iwsdk/* package, when iwsdk dev up reports guidance updated from an older release, or when errors appear right after an IWSDK version change.
|
|
4
|
+
argument-hint: '[target version, default latest]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Upgrade IWSDK
|
|
8
|
+
|
|
9
|
+
An upgrade has three parts: move the packages, apply what changed between the
|
|
10
|
+
two releases, and show that the app behaves as it did before. Do them in that
|
|
11
|
+
order.
|
|
12
|
+
|
|
13
|
+
## 1. Record the baseline first
|
|
14
|
+
|
|
15
|
+
Before changing any version, check `git status`, make sure the user's work is
|
|
16
|
+
saved or committed (do not commit unless the user allowed it), and record how
|
|
17
|
+
the app behaves now: run its typecheck and build scripts with the project's
|
|
18
|
+
package manager (for example `npm run typecheck` and `npm run build`).
|
|
19
|
+
|
|
20
|
+
Write down every error, then start the dev server and save the browser log and
|
|
21
|
+
a runtime screenshot. Older apps often have errors that predate the upgrade;
|
|
22
|
+
without a baseline you cannot tell them from new ones, and proving it later
|
|
23
|
+
costs a full reinstall.
|
|
24
|
+
|
|
25
|
+
## 2. Move the packages
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npx @iwsdk/cli@latest upgrade --dry-run
|
|
29
|
+
npx @iwsdk/cli@latest upgrade
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Always run it with `@latest`, even if the project has an older `@iwsdk/cli`:
|
|
33
|
+
the newest CLI carries every migration guide. For a specific release, add
|
|
34
|
+
`--to <version>` (`npx @iwsdk/cli@<version> upgrade` works only for releases
|
|
35
|
+
that include the `upgrade` command). It sets every `@iwsdk/*` package to the release, installs
|
|
36
|
+
with the project's package manager, aligns the `three` alias and an existing
|
|
37
|
+
`@types/three` with `@iwsdk/core`, refreshes this guidance, and writes to `.iwsdk/migrations/`:
|
|
38
|
+
|
|
39
|
+
- one `iwsdk-migrate-*/SKILL.md` for each release boundary that needs code
|
|
40
|
+
changes;
|
|
41
|
+
- `release-notes.md` with every change between the two versions.
|
|
42
|
+
|
|
43
|
+
It also checks `iwsdk.config.json` against the new release and lists settings
|
|
44
|
+
that no longer validate. Packages it reports as "not part of the IWSDK release"
|
|
45
|
+
were left as declared; remove one only if a migration guide says it was
|
|
46
|
+
retired. In a monorepo it installs with the workspace's package manager; if a
|
|
47
|
+
workspace-level override pins `three`, it tells you to change it.
|
|
48
|
+
|
|
49
|
+
If the user asked for a plain package-manager bump instead, do that, then run
|
|
50
|
+
`npx @iwsdk/cli@latest agents sync`; `iwsdk dev up` also refreshes unedited
|
|
51
|
+
guidance.
|
|
52
|
+
|
|
53
|
+
## 3. Apply what changed
|
|
54
|
+
|
|
55
|
+
1. Follow each migration guide in `.iwsdk/migrations/`, oldest first, before
|
|
56
|
+
other work.
|
|
57
|
+
2. Read the major and minor entries in `release-notes.md` and check whether
|
|
58
|
+
the app uses what they change (renamed settings, new required versions,
|
|
59
|
+
changed defaults).
|
|
60
|
+
3. Fix each `iwsdk.config.json` issue the upgrade listed.
|
|
61
|
+
4. Re-read the `iwsdk-agent-guidance` block in `AGENTS.md`: it now describes
|
|
62
|
+
the new release. Do not hand-edit guidance files; an edited file stops
|
|
63
|
+
receiving updates.
|
|
64
|
+
|
|
65
|
+
## 4. Prove it
|
|
66
|
+
|
|
67
|
+
Run the same checks as the baseline and compare. Report new errors and fix
|
|
68
|
+
them; report baseline errors separately as existing. A clean typecheck and
|
|
69
|
+
build do not show that the app renders: confirm the runtime screenshot and an
|
|
70
|
+
error-free browser log, and enter XR when the app is an XR app.
|
|
71
|
+
|
|
72
|
+
The upgrade is done when every migration guide is applied, the comparison
|
|
73
|
+
shows no new errors, and the user knows which existing errors remain.
|
|
74
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=5ccb37dbe152b3611496740e89bc8e42c8d59dfed8be7512635d877924b79988 name=iwsdk-upgrade (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -3,6 +3,8 @@ description: "Asset manifest contract"
|
|
|
3
3
|
globs:
|
|
4
4
|
- "src/assets.ts"
|
|
5
5
|
- "src/assets.js"
|
|
6
|
+
- "src/iwsdk/assets.ts"
|
|
7
|
+
- "src/iwsdk/assets.js"
|
|
6
8
|
- "src/scene-assets/**"
|
|
7
9
|
alwaysApply: false
|
|
8
10
|
---
|
|
@@ -57,3 +59,4 @@ mesh lowers to one `InstancedMesh`.
|
|
|
57
59
|
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
58
60
|
Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
|
|
59
61
|
`ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
|
|
62
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=e6b8d299d9f7590043801fae63d23de387e937bcb87bafe59b9b70f6e0622db3 name=assets-and-manifest.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -102,3 +102,4 @@ buttons. Browser controls live at `world.input.keyboard` and
|
|
|
102
102
|
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
103
103
|
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
104
104
|
`getWorldPosition()` when logic needs the true viewer position.
|
|
105
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=f09a86b27ce781f8e69b6471051167bee392ac2f503526df33ded757940268f6 name=ecs-api.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -71,3 +71,4 @@ back. Render each changed module before the root.
|
|
|
71
71
|
|
|
72
72
|
For composing a scene rather than editing one, use the `iwsdk-compose-scene`
|
|
73
73
|
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
74
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=f32c3e7d4024f56a3ff5ae32b42c236377551cbd3b2b231e84ada68362b68266 name=scene-json.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -65,3 +65,4 @@ can.
|
|
|
65
65
|
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
66
66
|
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
67
67
|
than improvising. This file is the format reference it relies on.
|
|
68
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=ce002bd4759a1d087c3e18fd3e2a9a009eb3bef5561d0a698f86726a1bd7f9c3 name=uikitml.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
package/dist/guidance/{copilot → files}/.github/instructions/assets-and-manifest.instructions.md
RENAMED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
applyTo: "src/assets.ts,src/assets.js,src/scene-assets/**"
|
|
2
|
+
applyTo: "src/assets.ts,src/assets.js,src/iwsdk/assets.ts,src/iwsdk/assets.js,src/scene-assets/**"
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Asset manifest contract
|
|
@@ -52,3 +52,4 @@ mesh lowers to one `InstancedMesh`.
|
|
|
52
52
|
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
53
53
|
Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
|
|
54
54
|
`ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
|
|
55
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=6949b512ef5bb71b488b7e8544b4e572f46f73f72a941b248a0856228299bfad name=assets-and-manifest.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -98,3 +98,4 @@ buttons. Browser controls live at `world.input.keyboard` and
|
|
|
98
98
|
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
99
99
|
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
100
100
|
`getWorldPosition()` when logic needs the true viewer position.
|
|
101
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=724a02986ce0999bc31c02b4f1e4a7b6b83c9966f994979a340e36b6243d26fd name=ecs-api.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -68,3 +68,4 @@ back. Render each changed module before the root.
|
|
|
68
68
|
|
|
69
69
|
For composing a scene rather than editing one, use the `iwsdk-compose-scene`
|
|
70
70
|
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
71
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=c73f635cec34f9e99b2bc59ffe63583842d40e419a499225a56cbb7838d9bccd name=scene-json.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -62,3 +62,4 @@ can.
|
|
|
62
62
|
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
63
63
|
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
64
64
|
than improvising. This file is the format reference it relies on.
|
|
65
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=f06c88f681a856a0b8b93b5552257dd316f189082dfc0a6bca87e2e642ecbb3e name=uikitml.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|