WebNN

Procedures

1. Inspect the workspace for browser entry points, UI handlers, worker entry files, and any existing model-loading or inference abstraction layer.
2. Execute

   node scripts/find-webnn-targets.mjs .

   to inventory likely frontend files and existing WebNN markers when a Node runtime is available.
3. If a Node runtime is unavailable, inspect the nearest

   package.json

   , HTML entry point, framework bootstrap files, and worker entry files manually to identify the browser app boundary.
4. If the workspace contains multiple frontend apps, prefer the app that contains the active route, component, or user-requested feature surface.
5. If the inventory still leaves multiple plausible frontend targets, stop and ask which app should receive the WebNN integration.
6. If the project is not a browser web app, stop and explain that this skill does not apply.

1. Read

   references/webnn-reference.md

   before writing code.
2. Read

   references/examples.md

   when choosing between a direct WebNN graph flow and an adapter around an existing browser ML runtime.
3. Read

   references/compatibility.md

   when native support, preview flags, device behavior, or backend differences matter.
4. Read

   references/troubleshooting.md

   when context creation, graph build, tensor readback, or device selection fails.
5. Verify that the feature runs in a secure context and in a

   Window

   or

   DedicatedWorker

   context.
6. If the feature must run on the server, train models, or depend on cloud inference, stop and explain the platform mismatch.
7. Choose device intent deliberately: use

   powerPreference: "high-performance"

   for throughput,

   powerPreference: "low-power"

   for power-efficient acceleration, or

   accelerated: false

   to prefer CPU inference for maximum reach.
8. Treat

   accelerated

   and

   powerPreference

   as preferences, not guarantees. Browser backends can still partition graphs or fall back per operator.
9. Choose a direct

   MLGraphBuilder

   flow when the application owns graph construction or can keep a small deterministic graph path.
10. Choose an adapter around an existing local runtime only when the application already loads models through that runtime and the task is to prefer WebNN acceleration without rewriting the full inference stack.
11. If the project uses TypeScript, add or preserve typings for the WebNN surface used by the project.

1. Read

   assets/webnn-runtime.template.ts

   and adapt it to the framework, state model, and file layout in the workspace.
2. Centralize support detection around

   window.isSecureContext

   ,

   navigator.ml

   , and the requested execution context instead of scattering checks through UI components.
3. Create an

   MLContext

   only at the boundary where the app is ready to initialize local inference.
4. Pass explicit

   accelerated

   and

   powerPreference

   values when the product has a real preference, and omit tuning that the product cannot justify.
5. Build the graph through

   MLGraphBuilder

   when the feature uses direct WebNN operations, or route existing model execution through the app's existing local runtime adapter when that runtime is already responsible for model loading and pre/post-processing.
6. Reuse the compiled graph and reusable tensors when input and output shapes stay stable across requests.
7. Use

   context.writeTensor()

   ,

   context.dispatch()

   , and

   await context.readTensor()

   in that order for direct graph execution.
8. Observe

   context.lost

   and rebuild the context, graph, and tensors if the browser invalidates the execution state.
9. Destroy tensors, graphs, and contexts when the feature is disposed or the route no longer needs them.

1. Surface distinct states for unsupported browsers, secure-context failures, runtime preparation, ready native execution, and explicit fallback execution.
2. Keep a non-WebNN path for unsupported browsers or unsupported devices when the feature must remain available.
3. Keep the fallback explicit and product-approved. Do not silently swap in a remote model provider when the feature is supposed to stay local.
4. Present device choice as an intent, not a promise that every operator will execute on that device.
5. Move long-running model preparation or repeated inference off the main thread when the application already uses a worker-friendly architecture.
6. Keep all user data handling consistent with the product's local-processing promises and privacy requirements.

1. Execute

   node scripts/find-webnn-targets.mjs .

   to confirm that the intended app boundary and WebNN markers still resolve to the edited integration surface.
2. Verify secure-context and

   navigator.ml

   detection before debugging deeper runtime issues.
3. For direct WebNN paths, run a smoke test that creates a context, builds a trivial graph, writes inputs, dispatches, and reads outputs.
4. Test the intended

   accelerated

   and

   powerPreference

   settings and confirm that fallback behavior remains usable when an accelerated context cannot be created.
5. Use

   context.opSupportLimits()

   when operator coverage or tensor data type support influences graph design.
6. Confirm the app does not reuse destroyed tensors, graphs, or contexts.
7. If the target environment depends on preview Chromium flags or milestone-specific behavior, confirm the required browser state from

   references/compatibility.md

   before treating runtime failures as application bugs.
8. Run the workspace build, typecheck, or tests after editing.

Error Handling

• If

  navigator.ml

  is missing, confirm secure-context requirements and browser support from

  references/compatibility.md

  before changing application code.
• If

  createContext()

  fails for an accelerated or high-performance request, retry only through the product's approved fallback plan and surface the failure reason.
• If

  build()

  or

  dispatch()

  fails, check

  references/examples.md

  and

  references/troubleshooting.md

  for operator, shape, and device mismatches before rewriting the feature.
• If

  context.lost

  resolves, treat the current context, graph, and tensors as invalid and recreate them before the next inference attempt.
• If the product only has a remote inference contract, stop and explain that this skill does not directly apply.