@colixsystems/widget-sdk 0.104.0 → 0.106.0

package/README.md

@@ -68,8 +68,30 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.104.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.106.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
+### What's new in 0.106.0 (contract 1.80.0)
+
+**A `required` `tableRef` can now say the table is the APP'S, not the widget's — `sharedTable: true` (sc-5982).** sc-2791's publish gate `manifest.requiredTableRefsHaveTemplate` counted only two kinds of satisfying table: one the widget seeds via `datastoreTemplate`, and one the host hands in when the in-Studio agent delegates a build. A widget that legitimately reads a table it does not own — a chart, a metric, a map, a manager view over another widget's table — could satisfy neither when publishing on its own, so the only way through the gate was to drop `required`. That trades a publish error for a worse runtime one: an unbound widget renders an empty tile and the author gets no warning. (In this repo it also took down every first-party publish for twelve days.)
+
+`sharedTable: true` on a `tableRef` property says "required, but the author supplies the table; I seed nothing for it". It exempts the property from the seeding duty only — the property stays `required`, the author must still bind a table, and the host still refuses to place the widget unbound. Pick between the two shapes by asking who owns the data:
+
+```js
+propertySchema: {
+  // The widget owns its data → seed it.
+  messagesTableId: { type: "tableRef", label: "Messages", required: true },
+  // The app owns the data, the author points at it → declare it shared.
+  sourceTableId: { type: "tableRef", label: "Source table", required: true, sharedTable: true },
+}
+```
+
+Leaving a `required` `tableRef` with neither a seeded table nor `sharedTable` is still rejected at publish, and the rejection still names the offending properties. Additive: every manifest that passed before passes now.
+
+### What's new in 0.105.0 (contract unchanged)
+
+**New linter rule `sdk-export-not-imported` — self-containment now covers the SDK surface, not just `React` (sc-5897).** `react-not-imported` (0.62.0) enforced that a referenced `React` global must be imported, but there was no equivalent rule for the SDK's own exports: source that called `useFilestoreFile(id)` — or rendered `<View>` — without naming it in `import { … } from "@colixsystems/widget-sdk"` linted clean, bundled clean, and threw `ReferenceError: useFilestoreFile is not defined` at render. The two failures are one bug, so they now share one detector, keyed off the names `CONTRACT.hooks` and `CONTRACT.primitives` already enumerate — a hook added to the contract is covered with no second list to maintain.
+
+The scan is AST-free, so it flags only the three reference forms text can decide with certainty: a call `NAME(`, a member read `NAME.` (`StyleSheet.create`), and a JSX element `<NAME`. Any other occurrence of the word — an import specifier, a local declaration or destructure, a property key, JSX text, a comment or string — means a binding the scan cannot see may exist, and the name is abandoned rather than flagged. `error` severity with no opt-out, matching `react-not-imported`. Author fix: add the name to your SDK import. `CONTRACT` is unchanged (no new field).
 ### What's new in 0.104.0 (contract 1.79.0)
 
 **Each corner can be rounded on its own — the `cornerRadius` property type.** A radius was a single number, so every rounded surface was rounded on all four corners: a card that meets the screen edge, a tab rounded only on top, or a bubble with one squared corner had no expression.
@@ -542,7 +564,7 @@ useEffect(() => {
 
 ### What's new in 0.57.0
 
-**A `required: true` `tableRef` must ship a matching `datastoreTemplate` table (sc-2791).** A widget property that the author cannot skip — a `tableRef` you mark `required: true` — must have a table to bind on install, or the end user has nothing to pick and the widget can't load its data. The marketplace analyzer now enforces this at publish: the check `manifest.requiredTableRefsHaveTemplate` rejects a manifest whose `datastoreTemplate.tables` count is fewer than its `required` `tableRef` property count, naming the offending properties. Two ways to clear it: seed a `datastoreTemplate` table for each required `tableRef` (the default — the widget owns its data), OR make the property **optional** when it binds a table the app already owns (shared data the user names). This tightens the existing "always ship a `datastoreTemplate` for a data widget" guidance into an enforced rule for the `required` case. No export, type, or hook changed shape — additive publish-gate + documentation. `CONTRACT` is unchanged (no new field).
+**A `required: true` `tableRef` must ship a matching `datastoreTemplate` table (sc-2791).** A widget property that the author cannot skip — a `tableRef` you mark `required: true` — must have a table to bind on install, or the end user has nothing to pick and the widget can't load its data. The marketplace analyzer now enforces this at publish: the check `manifest.requiredTableRefsHaveTemplate` rejects a manifest whose `datastoreTemplate.tables` count is fewer than its `required` `tableRef` property count, naming the offending properties. Two ways to clear it: seed a `datastoreTemplate` table for each required `tableRef` (the default — the widget owns its data), OR mark the property `sharedTable: true` when it binds a table the app already owns (0.106.0 — it stays `required`, so the author must still bind one). Dropping `required` also clears the gate but is the wrong fix: an optional table prop lets the widget ship unbound and render an empty tile. This tightens the existing "always ship a `datastoreTemplate` for a data widget" guidance into an enforced rule for the `required` case. No export, type, or hook changed shape — additive publish-gate + documentation. `CONTRACT` is unchanged (no new field).
 
 ### What's new in 0.55.0
 

package/dist/contract.cjs

@@ -1903,7 +1903,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for.",
   },
   translations: {
     type: "object",
@@ -3301,7 +3301,17 @@ const CONTRACT = deepFreeze({
   //    per-scalar limits never stated, so the worst-case unauthenticated
   //    payload is SMALLER than before. `__proto__`-style keys are refused at
   //    every level. Additive: every value accepted before is accepted now.
-  version: "1.79.0",
+  // 1.80.0: additive (sc-5982) — a `tableRef` property may declare
+  //    `sharedTable: true`: "required, but the author supplies the table; the
+  //    widget seeds nothing." The publish gate
+  //    `manifest.requiredTableRefsHaveTemplate` counted only seeded
+  //    `datastoreTemplate` tables and Mason-supplied bound tables, so a widget
+  //    that legitimately reads an app-owned table (Chart, Metric, Map, a
+  //    manager view) could never satisfy it when publishing standalone — which
+  //    blocked every first-party publish for twelve days. The flag separates
+  //    who PROVIDES the table from whether the author may skip it; `required`
+  //    still means required.
+  version: "1.80.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1903,7 +1903,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for.",
   },
   translations: {
     type: "object",
@@ -3301,7 +3301,17 @@ const CONTRACT = deepFreeze({
   //    per-scalar limits never stated, so the worst-case unauthenticated
   //    payload is SMALLER than before. `__proto__`-style keys are refused at
   //    every level. Additive: every value accepted before is accepted now.
-  version: "1.79.0",
+  // 1.80.0: additive (sc-5982) — a `tableRef` property may declare
+  //    `sharedTable: true`: "required, but the author supplies the table; the
+  //    widget seeds nothing." The publish gate
+  //    `manifest.requiredTableRefsHaveTemplate` counted only seeded
+  //    `datastoreTemplate` tables and Mason-supplied bound tables, so a widget
+  //    that legitimately reads an app-owned table (Chart, Metric, Map, a
+  //    manager view) could never satisfy it when publishing standalone — which
+  //    blocked every first-party publish for twelve days. The flag separates
+  //    who PROVIDES the table from whether the author may skip it; `required`
+  //    still means required.
+  version: "1.80.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/linter.cjs

@@ -714,43 +714,129 @@ function _lucideIconRules(source) {
   return findings;
 }
 
-// sc-2353 — widget source must be self-contained. The automatic JSX runtime
-// binds jsx/jsxs from react/jsx-runtime but never `React` itself, so a widget
-// that reaches for the bare `React` global (React.createElement / React.Fragment
-// / React.memo / React.useMemo) without importing it renders fine until a
-// non-initial code path hits the reference, then throws "React is not defined".
-// The platform does NOT inject a React binding — require an explicit
-// `import React from "react"` (or `import * as React`) whenever the source
-// references React, so the bundle is self-contained on both hosts and survives
-// a download → re-upload round-trip. Plain JSX needs no React import.
-const _REACT_DEFAULT_IMPORT_RE = /\bimport\s+(?:React\b|\*\s+as\s+React\b)/;
-const _REACT_MEMBER_USE_RE = /\bReact\s*\./;
-function _reactInScopeRules(source) {
+// sc-2353 / sc-5897 — widget source must be SELF-CONTAINED: every identifier it
+// references needs a binding in that file. Two rules share ONE detector here
+// because they are one bug with one cause (CLAUDE.md §3):
+//
+//   * `react-not-imported` (sc-2353) — the automatic JSX runtime binds
+//     jsx/jsxs from react/jsx-runtime but never `React` itself, so source that
+//     reaches for the bare `React` global (React.createElement / React.Fragment
+//     / React.memo) renders fine until a non-initial code path hits the
+//     reference, then throws "React is not defined". The platform does NOT
+//     inject a React binding. Plain JSX needs no React import.
+//   * `sdk-export-not-imported` (sc-5897) — an SDK hook or primitive referenced
+//     as a bare identifier (`useFilestoreFile(id)`, `<View>`) with no import
+//     throws the same ReferenceError. It used to lint clean and surface only at
+//     the render.smoke gate, where "<name> is not defined" is softenable — so
+//     it was demoted to an advisory warning and burned repair turns instead of
+//     being rejected deterministically here.
+//
+// The scan is AST-free, so it flags ONLY the three reference forms text can
+// decide with certainty — a call `NAME(`, a member read `NAME.`, and a JSX
+// element `<NAME`. Any OTHER occurrence of the word (an import specifier, a
+// declaration, a destructured local, a property key, JSX text) means a binding
+// this scan cannot see may exist, so the name is abandoned rather than flagged:
+// missing a real bug is recoverable, a false `error` with no opt-out blocks a
+// legitimate publish.
+const _IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+// CONTRACT enumerates the SDK's public hooks and primitives, so a name added
+// there is covered here without a second hand-maintained list.
+const _SDK_EXPORT_NAMES = Array.from(
+  new Set(
+    [...CONTRACT.hooks, ...CONTRACT.primitives]
+      .map((entry) => entry && entry.name)
+      .filter((name) => typeof name === "string" && _IDENTIFIER_RE.test(name)),
+  ),
+);
+
+// The only words that may legally precede an expression. A DECLARATION keyword
+// (`function`/`const`/`import`/`new`/`as`/…) is absent by design, and so is
+// every other identifier: `Call useTheme() now` is not valid JS, so a word lead
+// outside this set means the match sits in JSX text, not in code.
+const _EXPRESSION_LEAD_WORDS = new Set([
+  "return",
+  "await",
+  "typeof",
+  "void",
+  "delete",
+  "yield",
+  "throw",
+  "case",
+  "in",
+  "of",
+  "do",
+  "else",
+  "instanceof",
+]);
+
+// 1-based line of the first unbound reference to `name`, or 0 when the name is
+// bound, never referenced, or referenced in a form this scan cannot decide.
+function _unboundReferenceLine(code, name) {
+  if (!code.includes(name)) return 0;
+  // `NAME(…) {` is a function / method DEFINITION, not a call.
+  if (new RegExp(`\\b${name}\\s*\\([^()]*\\)\\s*\\{`).test(code)) return 0;
+  const word = new RegExp(`\\b${name}\\b`, "g");
+  let firstIndex = -1;
+  let match;
+  while ((match = word.exec(code))) {
+    const before = code.slice(0, match.index).replace(/\s+$/, "");
+    // `obj.NAME` / `obj?.NAME` / `{...NAME}` — never this binding.
+    if (before.endsWith(".")) continue;
+    const lead = before.slice(-1);
+    if (/[A-Za-z0-9_$]/.test(lead)) {
+      const leadWord = (before.match(/[A-Za-z_$][A-Za-z0-9_$]*$/) || [""])[0];
+      if (!_EXPRESSION_LEAD_WORDS.has(leadWord)) return 0;
+    } else if (lead === ">" && !before.endsWith("=>")) {
+      // A `>` that is not an arrow closes a JSX tag, so what follows is text.
+      return 0;
+    }
+    const after = code.slice(match.index + name.length).replace(/^\s+/, "");
+    const isReference =
+      /<\s*\/?$/.test(before) || after.startsWith("(") || after.startsWith(".");
+    if (!isReference) return 0;
+    if (firstIndex < 0) firstIndex = match.index;
+  }
+  if (firstIndex < 0) return 0;
+  return code.slice(0, firstIndex).split(/\r?\n/).length;
+}
+
+function _selfContainedReferenceRules(source) {
   const findings = [];
   const code = _stripNonCode(source);
-  if (!_REACT_MEMBER_USE_RE.test(code)) return findings;
-  if (_REACT_DEFAULT_IMPORT_RE.test(code)) return findings;
-  const codeLines = code.split(/\r?\n/);
   const sourceLines = source.split(/\r?\n/);
-  let line = 0;
-  for (let i = 0; i < codeLines.length; i += 1) {
-    if (_REACT_MEMBER_USE_RE.test(codeLines[i])) {
-      line = i + 1;
-      break;
-    }
+  const snippetAt = (line) => (sourceLines[line - 1] || "").trim().slice(0, 200);
+
+  const reactLine = _unboundReferenceLine(code, "React");
+  if (reactLine) {
+    findings.push({
+      rule: "react-not-imported",
+      severity: "error",
+      label:
+        "source references the `React` global (e.g. React.createElement / " +
+        "React.Fragment) but never imports it — widget source must be " +
+        'self-contained. Add `import React from "react";` at the top, or drop ' +
+        "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
+        "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
+      line: reactLine,
+      snippet: snippetAt(reactLine),
+    });
+  }
+
+  for (const name of _SDK_EXPORT_NAMES) {
+    const line = _unboundReferenceLine(code, name);
+    if (!line) continue;
+    findings.push({
+      rule: "sdk-export-not-imported",
+      severity: "error",
+      label:
+        `\`${name}\` is used but never imported — it throws ` +
+        `"${name} is not defined" at render. Import it from ` +
+        '"@colixsystems/widget-sdk"; widget source must be self-contained.',
+      line,
+      snippet: snippetAt(line),
+    });
   }
-  findings.push({
-    rule: "react-not-imported",
-    severity: "error",
-    label:
-      "source references the `React` global (e.g. React.createElement / " +
-      "React.Fragment) but never imports it — widget source must be " +
-      'self-contained. Add `import React from "react";` at the top, or drop ' +
-      "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
-      "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
-    line,
-    snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
-  });
   return findings;
 }
 
@@ -1195,7 +1281,7 @@ function lintSource(source, options) {
   findings.push(..._translationApiRules(source));
   findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
-  findings.push(..._reactInScopeRules(source));
+  findings.push(..._selfContainedReferenceRules(source));
   findings.push(..._imagePercentHeightRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.

package/dist/linter.js

@@ -835,43 +835,129 @@ function _lucideIconRules(source) {
   return findings;
 }
 
-// sc-2353 — widget source must be self-contained. The automatic JSX runtime
-// binds jsx/jsxs from react/jsx-runtime but never `React` itself, so a widget
-// that reaches for the bare `React` global (React.createElement / React.Fragment
-// / React.memo / React.useMemo) without importing it renders fine until a
-// non-initial code path hits the reference, then throws "React is not defined".
-// The platform does NOT inject a React binding — require an explicit
-// `import React from "react"` (or `import * as React`) whenever the source
-// references React, so the bundle is self-contained on both hosts and survives
-// a download → re-upload round-trip. Plain JSX needs no React import.
-const _REACT_DEFAULT_IMPORT_RE = /\bimport\s+(?:React\b|\*\s+as\s+React\b)/;
-const _REACT_MEMBER_USE_RE = /\bReact\s*\./;
-function _reactInScopeRules(source) {
+// sc-2353 / sc-5897 — widget source must be SELF-CONTAINED: every identifier it
+// references needs a binding in that file. Two rules share ONE detector here
+// because they are one bug with one cause (CLAUDE.md §3):
+//
+//   * `react-not-imported` (sc-2353) — the automatic JSX runtime binds
+//     jsx/jsxs from react/jsx-runtime but never `React` itself, so source that
+//     reaches for the bare `React` global (React.createElement / React.Fragment
+//     / React.memo) renders fine until a non-initial code path hits the
+//     reference, then throws "React is not defined". The platform does NOT
+//     inject a React binding. Plain JSX needs no React import.
+//   * `sdk-export-not-imported` (sc-5897) — an SDK hook or primitive referenced
+//     as a bare identifier (`useFilestoreFile(id)`, `<View>`) with no import
+//     throws the same ReferenceError. It used to lint clean and surface only at
+//     the render.smoke gate, where "<name> is not defined" is softenable — so
+//     it was demoted to an advisory warning and burned repair turns instead of
+//     being rejected deterministically here.
+//
+// The scan is AST-free, so it flags ONLY the three reference forms text can
+// decide with certainty — a call `NAME(`, a member read `NAME.`, and a JSX
+// element `<NAME`. Any OTHER occurrence of the word (an import specifier, a
+// declaration, a destructured local, a property key, JSX text) means a binding
+// this scan cannot see may exist, so the name is abandoned rather than flagged:
+// missing a real bug is recoverable, a false `error` with no opt-out blocks a
+// legitimate publish.
+const _IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+// CONTRACT enumerates the SDK's public hooks and primitives, so a name added
+// there is covered here without a second hand-maintained list.
+const _SDK_EXPORT_NAMES = Array.from(
+  new Set(
+    [...CONTRACT.hooks, ...CONTRACT.primitives]
+      .map((entry) => entry && entry.name)
+      .filter((name) => typeof name === "string" && _IDENTIFIER_RE.test(name)),
+  ),
+);
+
+// The only words that may legally precede an expression. A DECLARATION keyword
+// (`function`/`const`/`import`/`new`/`as`/…) is absent by design, and so is
+// every other identifier: `Call useTheme() now` is not valid JS, so a word lead
+// outside this set means the match sits in JSX text, not in code.
+const _EXPRESSION_LEAD_WORDS = new Set([
+  "return",
+  "await",
+  "typeof",
+  "void",
+  "delete",
+  "yield",
+  "throw",
+  "case",
+  "in",
+  "of",
+  "do",
+  "else",
+  "instanceof",
+]);
+
+// 1-based line of the first unbound reference to `name`, or 0 when the name is
+// bound, never referenced, or referenced in a form this scan cannot decide.
+function _unboundReferenceLine(code, name) {
+  if (!code.includes(name)) return 0;
+  // `NAME(…) {` is a function / method DEFINITION, not a call.
+  if (new RegExp(`\\b${name}\\s*\\([^()]*\\)\\s*\\{`).test(code)) return 0;
+  const word = new RegExp(`\\b${name}\\b`, "g");
+  let firstIndex = -1;
+  let match;
+  while ((match = word.exec(code))) {
+    const before = code.slice(0, match.index).replace(/\s+$/, "");
+    // `obj.NAME` / `obj?.NAME` / `{...NAME}` — never this binding.
+    if (before.endsWith(".")) continue;
+    const lead = before.slice(-1);
+    if (/[A-Za-z0-9_$]/.test(lead)) {
+      const leadWord = (before.match(/[A-Za-z_$][A-Za-z0-9_$]*$/) || [""])[0];
+      if (!_EXPRESSION_LEAD_WORDS.has(leadWord)) return 0;
+    } else if (lead === ">" && !before.endsWith("=>")) {
+      // A `>` that is not an arrow closes a JSX tag, so what follows is text.
+      return 0;
+    }
+    const after = code.slice(match.index + name.length).replace(/^\s+/, "");
+    const isReference =
+      /<\s*\/?$/.test(before) || after.startsWith("(") || after.startsWith(".");
+    if (!isReference) return 0;
+    if (firstIndex < 0) firstIndex = match.index;
+  }
+  if (firstIndex < 0) return 0;
+  return code.slice(0, firstIndex).split(/\r?\n/).length;
+}
+
+function _selfContainedReferenceRules(source) {
   const findings = [];
   const code = _stripNonCode(source);
-  if (!_REACT_MEMBER_USE_RE.test(code)) return findings;
-  if (_REACT_DEFAULT_IMPORT_RE.test(code)) return findings;
-  const codeLines = code.split(/\r?\n/);
   const sourceLines = source.split(/\r?\n/);
-  let line = 0;
-  for (let i = 0; i < codeLines.length; i += 1) {
-    if (_REACT_MEMBER_USE_RE.test(codeLines[i])) {
-      line = i + 1;
-      break;
-    }
+  const snippetAt = (line) => (sourceLines[line - 1] || "").trim().slice(0, 200);
+
+  const reactLine = _unboundReferenceLine(code, "React");
+  if (reactLine) {
+    findings.push({
+      rule: "react-not-imported",
+      severity: "error",
+      label:
+        "source references the `React` global (e.g. React.createElement / " +
+        "React.Fragment) but never imports it — widget source must be " +
+        'self-contained. Add `import React from "react";` at the top, or drop ' +
+        "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
+        "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
+      line: reactLine,
+      snippet: snippetAt(reactLine),
+    });
+  }
+
+  for (const name of _SDK_EXPORT_NAMES) {
+    const line = _unboundReferenceLine(code, name);
+    if (!line) continue;
+    findings.push({
+      rule: "sdk-export-not-imported",
+      severity: "error",
+      label:
+        `\`${name}\` is used but never imported — it throws ` +
+        `"${name} is not defined" at render. Import it from ` +
+        '"@colixsystems/widget-sdk"; widget source must be self-contained.',
+      line,
+      snippet: snippetAt(line),
+    });
   }
-  findings.push({
-    rule: "react-not-imported",
-    severity: "error",
-    label:
-      "source references the `React` global (e.g. React.createElement / " +
-      "React.Fragment) but never imports it — widget source must be " +
-      'self-contained. Add `import React from "react";` at the top, or drop ' +
-      "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
-      "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
-    line,
-    snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
-  });
   return findings;
 }
 
@@ -1372,8 +1458,9 @@ export function lintSource(source, options) {
   findings.push(..._translationApiRules(source));
   findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
-  // sc-2353 — widget source must be self-contained (reference React ⇒ import it).
-  findings.push(..._reactInScopeRules(source));
+  // sc-2353 / sc-5897 — widget source must be self-contained: a referenced
+  // `React` global or SDK export with no import throws at render.
+  findings.push(..._selfContainedReferenceRules(source));
   // sc-3493 — soft warning: percentage height on an <Image> collapses to 0.
   findings.push(..._imagePercentHeightRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.104.0",
+  "version": "0.106.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",