@stacksjs/stx 0.2.10 → 0.2.12

package/dist/types/config-types.d.ts

@@ -216,10 +216,43 @@ export declare interface StrictModeConfig {
   failOnViolation?: boolean
   allowPatterns?: string[]
 }
+/**
+ * Real-time broadcasting configuration.
+ *
+ * When enabled, stx starts a ts-broadcasting WebSocket server
+ * alongside the dev server so pages can receive push events.
+ */
+export declare interface BroadcastingConfig {
+  enabled?: boolean
+  driver?: 'bun' | 'reverb' | 'pusher' | 'ably' | 'log' | 'null'
+  host?: string
+  port?: number
+  scheme?: 'ws' | 'wss'
+  verbose?: boolean
+}
+/**
+ * App head configuration — auto-generates the document shell.
+ * No .stx file needs to write <!DOCTYPE>, <html>, <head>, or <body>.
+ */
+export declare interface AppHeadConfig {
+  title?: string
+  lang?: string
+  meta?: Array<Record<string, string>>
+  link?: Array<Record<string, string>>
+  script?: Array<{ src?: string, content?: string, [key: string]: any }>
+  headRaw?: string
+  bodyClass?: string
+  bodyAttrs?: Record<string, string>
+}
 /**
  * stx configuration options
  */
 export declare interface StxConfig {
+  app?: {
+    head?: AppHeadConfig
+  }
+  root?: string
+  pagesDir?: string
   templatesDir?: string
   defaultTitle?: string
   defaultDescription?: string
@@ -232,7 +265,13 @@ export declare interface StxConfig {
   partialsDir: string
   componentsDir: string
   layoutsDir?: string
+  storesDir?: string
   defaultLayout?: string
+  plugins?: Array<string | [string, Record<string, any>]>
+  publicDir?: string
+  envFile?: string | boolean
+  envPrefix?: string
+  css?: string | { config?: string, content?: string[], preflight?: boolean, minify?: boolean }
   debug: boolean
   cachePath: string
   customDirectives?: CustomDirective[]
@@ -261,6 +300,29 @@ export declare interface StxConfig {
   build?: Partial<BuildConfig>
   media?: Partial<MediaConfig>
   strict?: boolean | StrictModeConfig
+  buildMode?: 'compile' | 'serve'
+  autoShell?: boolean
+  outputDir?: string
+  shell?: string | false
+  broadcasting?: Partial<BroadcastingConfig>
+  apiRoutes?: Record<string, (request: Request) => Response | Promise<Response>>
+  router?: {
+    enabled?: boolean
+    container?: string
+    linkSelector?: string
+    viewTransitions?: boolean
+    viewTransitionDuration?: number
+    viewTransitionEasing?: string
+    scrollToTop?: boolean
+    prefetch?: boolean
+    cache?: boolean
+    cacheTTL?: number
+    skipSelectors?: string
+    viewTransitionCSS?: Record<string, string>
+    progressColor?: string
+    progressHeight?: string
+  }
+  apiRouter?: { handleRequest: (request: Request) => Response | Promise<Response> }
 }
 /**
  * SSG Build configuration for static site generation

package/dist/validator.d.ts

@@ -36,6 +36,7 @@ export declare function getPositionInfo(template: string, position: number): { l
  * @param params - Parameters passed to the directive
  * @returns Validation errors, if any
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function validateDirective(directiveName: string, content: string, params: string[]): TemplateValidationError[];
 /**
  * Check if a template has any directives

package/dist/variable-extractor.d.ts

@@ -19,7 +19,7 @@ export declare function extractVariables(scriptContent: string, context: Record<
  * @param scriptContent - ES module style script content
  * @returns CommonJS compatible script
  */
-export declare function convertToCommonJS(scriptContent: string): string;
+export declare function convertToCommonJS(scriptContent: string, filePath?: string): string;
 /**
  * Extract script content from an HTML template
  *

package/dist/view-composers.d.ts

@@ -168,4 +168,5 @@ export declare function clearComposers(): void;
  * }
  * ```
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export type ViewComposerCallback = (context: Record<string, any>, filePath: string) => void | Promise<void>;

package/dist/virtual-scrolling.d.ts

@@ -28,6 +28,7 @@ export declare function processInfiniteListDirectives(template: string, context?
  * Process @virtualGrid directives for grid virtualization
  */
 export declare function processVirtualGridDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * Virtual Scrolling Module
  *

package/dist/visual-testing.js

@@ -1,6 +1,6 @@
 // @bun
-import B from"fs";import $ from"path";import k from"crypto";var V=[{name:"mobile",width:375,height:667,isMobile:!0,hasTouch:!0},{name:"tablet",width:768,height:1024,isMobile:!0,hasTouch:!0},{name:"desktop",width:1280,height:800,isMobile:!1,hasTouch:!1},{name:"wide",width:1920,height:1080,isMobile:!1,hasTouch:!1}];function J(N={}){let Y={snapshotDir:N.snapshotDir||"__snapshots__",screenshotDir:N.screenshotDir||"__screenshots__",updateSnapshots:N.updateSnapshots||process.env.UPDATE_SNAPSHOTS==="true",threshold:N.threshold??0.01,viewports:N.viewports||V,generateDiff:N.generateDiff??!0,diffDir:N.diffDir||"__diffs__",compare:N.compare||b,ci:N.ci??process.env.CI==="true",retries:N.retries??(N.ci?3:1)};return{async snapshot(M,X){let q=$.join(Y.snapshotDir,`${X}.html`),G=C(M),Q=K(G);if(B.existsSync(q)){let W=await Bun.file(q).text(),Z=K(C(W));if(Q===Z)return{passed:!0,snapshotPath:q,message:"Snapshot matches"};if(Y.updateSnapshots)return await B.promises.mkdir($.dirname(q),{recursive:!0}),await Bun.write(q,G),{passed:!0,snapshotPath:q,message:"Snapshot updated"};let F=$.join(Y.diffDir,`${X}.actual.html`),U=$.join(Y.diffDir,`${X}.diff.html`);return await B.promises.mkdir(Y.diffDir,{recursive:!0}),await Bun.write(F,G),await Bun.write(U,I(W,G)),{passed:!1,snapshotPath:q,actualPath:F,diffPath:U,message:"Snapshot does not match"}}return await B.promises.mkdir($.dirname(q),{recursive:!0}),await Bun.write(q,G),{passed:!0,snapshotPath:q,message:"New snapshot created"}},async snapshotJson(M,X){let q=$.join(Y.snapshotDir,`${X}.json`),G=JSON.stringify(M,null,2);if(B.existsSync(q)){let Q=await Bun.file(q).text();if(G===Q)return{passed:!0,snapshotPath:q};if(Y.updateSnapshots)return await Bun.write(q,G),{passed:!0,snapshotPath:q,message:"Snapshot updated"};return{passed:!1,snapshotPath:q,message:`JSON snapshot mismatch:
-${z(Q,G)}`}}return await B.promises.mkdir($.dirname(q),{recursive:!0}),await Bun.write(q,G),{passed:!0,snapshotPath:q,message:"New snapshot created"}},matchInlineSnapshot(M,X){let q=C(M);if(X===void 0)return{passed:!0,expected:q};let G=C(X);return{passed:q===G,expected:q}},getConfig(){return Y}}}function D(N={}){let Y=J(N),M=Y.getConfig();return{async compareScreenshots(X,q,G="desktop"){let Q=$.join(M.screenshotDir,G,`${X}.png`),W=$.join(M.diffDir,G,`${X}.actual.png`),Z=$.join(M.diffDir,G,`${X}.diff.png`);if(B.existsSync(Q)){let F=await Bun.file(Q).arrayBuffer(),U=Buffer.from(F),_=await M.compare(q,U);if(_.match||_.diffPercentage<=M.threshold)return{viewport:G,passed:!0,baselinePath:Q};if(M.updateSnapshots)return await B.promises.mkdir($.dirname(Q),{recursive:!0}),await Bun.write(Q,q),{viewport:G,passed:!0,baselinePath:Q};if(await B.promises.mkdir($.dirname(W),{recursive:!0}),await Bun.write(W,q),_.diffImage&&M.generateDiff)await Bun.write(Z,_.diffImage);return{viewport:G,passed:!1,baselinePath:Q,actualPath:W,diffPath:M.generateDiff?Z:void 0,diffPercentage:_.diffPercentage}}return await B.promises.mkdir($.dirname(Q),{recursive:!0}),await Bun.write(Q,q),{viewport:G,passed:!0,baselinePath:Q}},async testViewports(X,q,G=M.viewports){let Q=[];for(let W of G){let Z=null;for(let F=0;F<M.retries;F++)try{let U=await q(W),_=await this.compareScreenshots(X,U,W.name);Q.push(_),Z=null;break}catch(U){if(Z=U,F<M.retries-1)await new Promise((_)=>setTimeout(_,100*(F+1)))}if(Z)Q.push({viewport:W.name,passed:!1,baselinePath:"",diffPercentage:100})}return Q},getSnapshotTester(){return Y}}}function L(N={}){let M=D(N).getSnapshotTester(),X=new Map;return{addStory(q){X.set(`${q.component}/${q.name}`,q)},addStories(q){for(let G of q)this.addStory(G)},getStories(){return Array.from(X.values())},getStoriesForComponent(q){return Array.from(X.values()).filter((G)=>G.component===q)},async testStory(q){let G=X.get(q);if(!G)return{name:q,passed:!1,duration:0,snapshots:[],screenshots:[],errors:[Error(`Story not found: ${q}`)]};let Q=Date.now(),W={name:q,passed:!0,duration:0,snapshots:[],screenshots:[],errors:[]};try{let Z=await G.render(),F=await M.snapshot(Z,q.replace(/\//g,"-"));if(W.snapshots.push(F),!F.passed)W.passed=!1}catch(Z){W.passed=!1,W.errors.push(Z)}return W.duration=Date.now()-Q,W},async testAllStories(){let q=[];for(let G of X.keys()){let Q=await this.testStory(G);q.push(Q)}return q},async generateStoryIndex(){let q={};for(let G of X.values()){if(!q[G.component])q[G.component]=[];q[G.component].push({name:G.name,args:G.args})}return JSON.stringify(q,null,2)}}}async function S(N,Y={}){let M={outputDir:Y.outputDir||"visual-test-report",format:Y.format||"html",title:Y.title||"Visual Test Report",includeScreenshots:Y.includeScreenshots??!0};await B.promises.mkdir(M.outputDir,{recursive:!0});let X=N.length,q=N.filter((F)=>F.passed).length,G=X-q,Q=N.reduce((F,U)=>F+U.duration,0);if(M.format==="json"){let F={title:M.title,summary:{total:X,passed:q,failed:G,duration:Q},results:N,generatedAt:new Date().toISOString()},U=$.join(M.outputDir,"report.json");return await Bun.write(U,JSON.stringify(F,null,2)),U}if(M.format==="markdown"){let F=`# ${M.title}
+import B from"fs";import $ from"path";import k from"crypto";var V=[{name:"mobile",width:375,height:667,isMobile:!0,hasTouch:!0},{name:"tablet",width:768,height:1024,isMobile:!0,hasTouch:!0},{name:"desktop",width:1280,height:800,isMobile:!1,hasTouch:!1},{name:"wide",width:1920,height:1080,isMobile:!1,hasTouch:!1}];function J(N={}){let Y={snapshotDir:N.snapshotDir||"__snapshots__",screenshotDir:N.screenshotDir||"__screenshots__",updateSnapshots:N.updateSnapshots||process.env.UPDATE_SNAPSHOTS==="true",threshold:N.threshold??0.01,viewports:N.viewports||V,generateDiff:N.generateDiff??!0,diffDir:N.diffDir||"__diffs__",compare:N.compare||b,ci:N.ci??process.env.CI==="true",retries:N.retries??(N.ci?3:1)};return{async snapshot(M,X){let q=$.join(Y.snapshotDir,`${X}.html`),G=C(M),Q=K(G);if(await Bun.file(q).exists()){let W=await Bun.file(q).text(),Z=K(C(W));if(Q===Z)return{passed:!0,snapshotPath:q,message:"Snapshot matches"};if(Y.updateSnapshots)return await B.promises.mkdir($.dirname(q),{recursive:!0}),await Bun.write(q,G),{passed:!0,snapshotPath:q,message:"Snapshot updated"};let F=$.join(Y.diffDir,`${X}.actual.html`),U=$.join(Y.diffDir,`${X}.diff.html`);return await B.promises.mkdir(Y.diffDir,{recursive:!0}),await Bun.write(F,G),await Bun.write(U,I(W,G)),{passed:!1,snapshotPath:q,actualPath:F,diffPath:U,message:"Snapshot does not match"}}return await B.promises.mkdir($.dirname(q),{recursive:!0}),await Bun.write(q,G),{passed:!0,snapshotPath:q,message:"New snapshot created"}},async snapshotJson(M,X){let q=$.join(Y.snapshotDir,`${X}.json`),G=JSON.stringify(M,null,2);if(await Bun.file(q).exists()){let Q=await Bun.file(q).text();if(G===Q)return{passed:!0,snapshotPath:q};if(Y.updateSnapshots)return await Bun.write(q,G),{passed:!0,snapshotPath:q,message:"Snapshot updated"};return{passed:!1,snapshotPath:q,message:`JSON snapshot mismatch:
+${z(Q,G)}`}}return await B.promises.mkdir($.dirname(q),{recursive:!0}),await Bun.write(q,G),{passed:!0,snapshotPath:q,message:"New snapshot created"}},matchInlineSnapshot(M,X){let q=C(M);if(X===void 0)return{passed:!0,expected:q};let G=C(X);return{passed:q===G,expected:q}},getConfig(){return Y}}}function D(N={}){let Y=J(N),M=Y.getConfig();return{async compareScreenshots(X,q,G="desktop"){let Q=$.join(M.screenshotDir,G,`${X}.png`),W=$.join(M.diffDir,G,`${X}.actual.png`),Z=$.join(M.diffDir,G,`${X}.diff.png`);if(await Bun.file(Q).exists()){let F=await Bun.file(Q).arrayBuffer(),U=Buffer.from(F),_=await M.compare(q,U);if(_.match||_.diffPercentage<=M.threshold)return{viewport:G,passed:!0,baselinePath:Q};if(M.updateSnapshots)return await B.promises.mkdir($.dirname(Q),{recursive:!0}),await Bun.write(Q,q),{viewport:G,passed:!0,baselinePath:Q};if(await B.promises.mkdir($.dirname(W),{recursive:!0}),await Bun.write(W,q),_.diffImage&&M.generateDiff)await Bun.write(Z,_.diffImage);return{viewport:G,passed:!1,baselinePath:Q,actualPath:W,diffPath:M.generateDiff?Z:void 0,diffPercentage:_.diffPercentage}}return await B.promises.mkdir($.dirname(Q),{recursive:!0}),await Bun.write(Q,q),{viewport:G,passed:!0,baselinePath:Q}},async testViewports(X,q,G=M.viewports){let Q=[];for(let W of G){let Z=null;for(let F=0;F<M.retries;F++)try{let U=await q(W),_=await this.compareScreenshots(X,U,W.name);Q.push(_),Z=null;break}catch(U){if(Z=U,F<M.retries-1)await new Promise((_)=>setTimeout(_,100*(F+1)))}if(Z)Q.push({viewport:W.name,passed:!1,baselinePath:"",diffPercentage:100})}return Q},getSnapshotTester(){return Y}}}function L(N={}){let M=D(N).getSnapshotTester(),X=new Map;return{addStory(q){X.set(`${q.component}/${q.name}`,q)},addStories(q){for(let G of q)this.addStory(G)},getStories(){return Array.from(X.values())},getStoriesForComponent(q){return Array.from(X.values()).filter((G)=>G.component===q)},async testStory(q){let G=X.get(q);if(!G)return{name:q,passed:!1,duration:0,snapshots:[],screenshots:[],errors:[Error(`Story not found: ${q}`)]};let Q=Date.now(),W={name:q,passed:!0,duration:0,snapshots:[],screenshots:[],errors:[]};try{let Z=await G.render(),F=await M.snapshot(Z,q.replace(/\//g,"-"));if(W.snapshots.push(F),!F.passed)W.passed=!1}catch(Z){W.passed=!1,W.errors.push(Z)}return W.duration=Date.now()-Q,W},async testAllStories(){let q=[];for(let G of X.keys()){let Q=await this.testStory(G);q.push(Q)}return q},async generateStoryIndex(){let q={};for(let G of X.values()){if(!q[G.component])q[G.component]=[];q[G.component].push({name:G.name,args:G.args})}return JSON.stringify(q,null,2)}}}async function S(N,Y={}){let M={outputDir:Y.outputDir||"visual-test-report",format:Y.format||"html",title:Y.title||"Visual Test Report",includeScreenshots:Y.includeScreenshots??!0};await B.promises.mkdir(M.outputDir,{recursive:!0});let X=N.length,q=N.filter((F)=>F.passed).length,G=X-q,Q=N.reduce((F,U)=>F+U.duration,0);if(M.format==="json"){let F={title:M.title,summary:{total:X,passed:q,failed:G,duration:Q},results:N,generatedAt:new Date().toISOString()},U=$.join(M.outputDir,"report.json");return await Bun.write(U,JSON.stringify(F,null,2)),U}if(M.format==="markdown"){let F=`# ${M.title}
 
 `;F+=`## Summary
 

package/dist/web-components.d.ts

@@ -170,6 +170,7 @@ export declare function generateSFCWebComponent(parsed: ParsedSFCComponent): str
  * </style>
  * ```
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function webComponentDirectiveHandler(content: string, params: string[], context: Record<string, any>, filePath: string): Promise<string>;
 /**
  * Property definition for reactive web components

package/dist/x-element.d.ts

@@ -1,3 +1,4 @@
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * x-element: Lightweight two-way binding for STX
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/stx",
   "type": "module",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "A performant UI Framework. Powered by Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -60,6 +60,16 @@
       "types": "./dist/bundle-analyzer.d.ts",
       "import": "./dist/bundle-analyzer.js"
     },
+    "./composables": {
+      "bun": "./dist/composables/index.js",
+      "types": "./dist/composables/index.d.ts",
+      "import": "./dist/composables/index.js"
+    },
+    "./composables/*": {
+      "bun": "./dist/composables/*.js",
+      "types": "./dist/composables/*.d.ts",
+      "import": "./dist/composables/*.js"
+    },
     "./*": {
       "import": "./dist/*"
     }
@@ -72,7 +82,8 @@
   "files": [
     "LICENSE.md",
     "README.md",
-    "dist"
+    "dist",
+    "stx.d.ts"
   ],
   "scripts": {
     "build": "bun run build:css && bun --bun build.ts",
@@ -103,14 +114,15 @@
     "typecheck": "bun tsc --noEmit"
   },
   "dependencies": {
-    "@cwcss/crosswind": "^0.1.6",
+    "@cwcss/crosswind": "^0.2.0",
     "@stacksjs/clapp": "^0.2.0",
-    "@stacksjs/desktop": "0.2.10",
-    "@stacksjs/sanitizer": "0.2.10",
+    "@stacksjs/desktop": "0.2.12",
+    "@stacksjs/sanitizer": "0.2.12",
     "@stacksjs/ts-craft": "^0.0.2",
-    "bun-plugin-stx": "0.2.10",
+    "bun-plugin-stx": "0.2.12",
     "bunfig": "^0.15.6",
-    "stx-router": "0.2.10",
+    "stx-router": "0.2.12",
+    "ts-broadcasting": "^0.0.4",
     "ts-syntax-highlighter": "^0.2.1"
   }
 }

package/stx.d.ts

@@ -0,0 +1,437 @@
+/**
+ * STX Ambient Type Declarations
+ *
+ * This file is shipped with the @stacksjs/stx package and referenced from
+ * the package's main types entry. When stx is installed, TypeScript picks
+ * these declarations up automatically — apps do NOT need to write their own
+ * stx.d.ts workaround for runtime globals.
+ *
+ * What's declared here:
+ *   1. Module declarations for `*.stx` and `*.md` imports
+ *   2. Runtime globals injected by the stx signals runtime into <script client>
+ *      blocks (signals, lifecycle, stores, composables, head, routing, etc.)
+ *   3. The `window.stx` registry interface
+ *
+ * Source of truth for the auto-imported global list:
+ *   packages/stx/src/client-script.ts → STX_AUTO_IMPORTS
+ *   packages/stx/src/signals.ts → window.stx = { ... }
+ */
+
+// ============================================================================
+// Module declarations
+// ============================================================================
+
+// Allow importing .stx files
+declare module '*.stx'
+
+// Allow importing .md files with frontmatter
+declare module '*.md' {
+  const content: string
+  const data: Record<string, any>
+  export default content
+  export { data }
+}
+
+// ============================================================================
+// Signal types
+// ============================================================================
+
+interface StxSignal<T> {
+  (): T
+  set: (value: T) => void
+  update: (fn: (current: T) => T) => void
+  subscribe: (cb: (value: T) => void) => () => void
+  readonly _isSignal: true
+}
+
+interface StxDerivedSignal<T> {
+  (): T
+  readonly _isSignal: true
+}
+
+interface StxRef<T> {
+  value: T
+}
+
+type StxCleanup = () => void
+
+// ============================================================================
+// Signals (modern reactivity)
+// ============================================================================
+
+declare function state<T>(initial: T): StxSignal<T>
+declare function derived<T>(compute: () => T): StxDerivedSignal<T>
+declare function effect(fn: () => void | StxCleanup): StxCleanup
+declare function batch(fn: () => void): void
+declare function untrack<T>(value: T | StxSignal<T> | StxDerivedSignal<T>): T
+declare function peek<T>(fn: () => T): T
+declare function isSignal(value: unknown): value is StxSignal<unknown>
+declare function isDerived(value: unknown): value is StxDerivedSignal<unknown>
+
+// ============================================================================
+// Lifecycle
+// ============================================================================
+
+declare function onMount(fn: () => void | StxCleanup): void
+declare function onDestroy(fn: () => void): void
+declare function onBeforeMount(fn: () => void): void
+declare function onMounted(fn: () => void | StxCleanup): void
+declare function onBeforeUpdate(fn: () => void): void
+declare function onUpdated(fn: () => void): void
+declare function onBeforeUnmount(fn: () => void): void
+declare function onUnmounted(fn: () => void): void
+declare function onErrorCaptured(fn: (error: unknown, instance: any, info: string) => boolean | void): void
+
+// ============================================================================
+// Template refs
+// ============================================================================
+
+declare function useRef<T = HTMLElement>(name: string): { current: T | null }
+
+// ============================================================================
+// Routing / navigation
+// ============================================================================
+
+declare function navigate(url: string, options?: { replace?: boolean }): void
+declare function goBack(): void
+declare function goForward(): void
+declare function useRoute(): {
+  path: string
+  params: Record<string, string>
+  query: Record<string, string>
+  hash: string
+}
+declare function setRouteParams(params: Record<string, string>): void
+declare function useSearchParams(): {
+  get: (key: string) => string | null
+  set: (key: string, value: string) => void
+  delete: (key: string) => void
+  has: (key: string) => boolean
+}
+
+// ============================================================================
+// Data fetching
+// ============================================================================
+
+interface StxQueryResult<T> {
+  data: StxSignal<T | null>
+  loading: StxSignal<boolean>
+  error: StxSignal<Error | null>
+  refetch: () => Promise<void>
+}
+
+interface StxMutationResult<T> {
+  data: StxSignal<T | null>
+  loading: StxSignal<boolean>
+  error: StxSignal<Error | null>
+  mutate: (body?: any) => Promise<T>
+}
+
+declare function useFetch<T = any>(url: string, options?: any): StxQueryResult<T>
+declare function useQuery<T = any>(url: string, options?: any): StxQueryResult<T>
+declare function useMutation<T = any>(url: string, options?: any): StxMutationResult<T>
+
+// ============================================================================
+// DOM utilities
+// ============================================================================
+
+declare function useEventListener<K extends keyof WindowEventMap>(
+  target: Window | Document | HTMLElement | string | null,
+  event: K,
+  handler: (event: WindowEventMap[K]) => void,
+  options?: boolean | AddEventListenerOptions,
+): StxCleanup
+declare function useEventListener(
+  target: Window | Document | HTMLElement | string | null,
+  event: string,
+  handler: (event: Event) => void,
+  options?: boolean | AddEventListenerOptions,
+): StxCleanup
+declare function useMeta(meta: Record<string, string>): void
+declare function useClickOutside(target: any, handler: (event: MouseEvent) => void): StxCleanup
+declare function useFocus(target: any): { focused: StxSignal<boolean>, focus: () => void, blur: () => void }
+
+// ============================================================================
+// Timers / scheduling
+// ============================================================================
+
+declare function useDebounce<T extends (...args: any[]) => any>(fn: T, delay: number): T
+declare function useDebouncedValue<T>(value: StxSignal<T>, delay: number): StxSignal<T>
+declare function useThrottle<T extends (...args: any[]) => any>(fn: T, delay: number): T
+declare function useInterval(fn: () => void, ms: number, options?: { immediate?: boolean }): {
+  start: () => void
+  stop: () => void
+  isActive: StxSignal<boolean>
+}
+declare function useTimeout(fn: () => void, ms: number): {
+  start: () => void
+  stop: () => void
+  isPending: StxSignal<boolean>
+}
+declare function nextTick(fn?: () => void): Promise<void>
+
+// ============================================================================
+// State utilities
+// ============================================================================
+
+declare function useToggle(initial?: boolean): [StxSignal<boolean>, (value?: boolean) => void]
+declare function useCounter(initial?: number, options?: { min?: number, max?: number }): {
+  count: StxSignal<number>
+  inc: (n?: number) => void
+  dec: (n?: number) => void
+  set: (n: number) => void
+  reset: () => void
+}
+declare function useAsync<T>(fn: () => Promise<T>): {
+  data: StxSignal<T | null>
+  loading: StxSignal<boolean>
+  error: StxSignal<Error | null>
+  execute: () => Promise<T>
+}
+
+// ============================================================================
+// Storage
+// ============================================================================
+
+declare function useLocalStorage<T>(key: string, defaultValue: T): StxSignal<T>
+declare function useSessionStorage<T>(key: string, defaultValue: T): StxSignal<T>
+
+// ============================================================================
+// WebSocket
+// ============================================================================
+
+declare function useWebSocket(url: string, options?: {
+  immediate?: boolean
+  autoReconnect?: boolean | { retries?: number, delay?: number }
+  onMessage?: (event: MessageEvent) => void
+  onConnected?: () => void
+  onDisconnected?: () => void
+  onError?: (event: Event) => void
+}): {
+  status: StxSignal<'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED'>
+  data: StxSignal<any>
+  send: (data: string | ArrayBuffer | Blob) => void
+  open: () => void
+  close: () => void
+  ws: WebSocket | null
+}
+
+// ============================================================================
+// Color mode
+// ============================================================================
+
+declare function useColorMode(): {
+  mode: StxSignal<'light' | 'dark' | 'auto'>
+  setMode: (mode: 'light' | 'dark' | 'auto') => void
+}
+declare function useDark(): StxSignal<boolean>
+
+// ============================================================================
+// Head / SEO
+// ============================================================================
+
+interface StxHeadConfig {
+  title?: string
+  titleTemplate?: string | ((title?: string) => string)
+  meta?: Array<Record<string, string>>
+  link?: Array<Record<string, string>>
+  script?: Array<Record<string, string> & { children?: string }>
+  style?: Array<Record<string, string> & { children?: string }>
+  htmlAttrs?: Record<string, string>
+  bodyAttrs?: Record<string, string>
+}
+
+interface StxSeoMetaConfig {
+  title?: string
+  description?: string
+  keywords?: string
+  author?: string
+  ogTitle?: string
+  ogDescription?: string
+  ogImage?: string
+  ogUrl?: string
+  ogType?: string
+  twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  twitterTitle?: string
+  twitterDescription?: string
+  twitterImage?: string
+  robots?: string
+  canonical?: string
+}
+
+declare function useHead(config: StxHeadConfig): void
+declare function useSeoMeta(config: StxSeoMetaConfig): void
+
+// ============================================================================
+// Vue-style reactivity (alternative API)
+// ============================================================================
+
+declare function ref<T>(value: T): StxRef<T>
+declare function reactive<T extends object>(target: T): T
+declare function computed<T>(getter: () => T): StxRef<T>
+declare function watch<T>(
+  source: (() => T) | StxRef<T> | StxSignal<T>,
+  callback: (value: T, oldValue: T) => void,
+  options?: { immediate?: boolean, deep?: boolean },
+): StxCleanup
+declare function watchEffect(fn: () => void): StxCleanup
+declare function watchMultiple(
+  sources: Array<() => any>,
+  callback: (values: any[], oldValues: any[]) => void,
+  options?: { immediate?: boolean },
+): StxCleanup
+
+// ============================================================================
+// Component definition / composition API
+// ============================================================================
+
+declare function defineProps<T extends Record<string, any> = Record<string, any>>(definitions?: any): T
+declare function withDefaults<T extends Record<string, any>>(props: T, defaults: Partial<T>): T
+declare function defineEmits<T extends string = string>(): (event: T, payload?: any) => void
+declare function defineExpose<T extends Record<string, any>>(exposed: T): void
+declare function provide<T>(key: string | symbol, value: T): void
+declare function inject<T>(key: string | symbol, defaultValue?: T): T | undefined
+declare function getCurrentInstance(): any
+declare function useSlots(): Record<string, any>
+declare function useAttrs(): Record<string, any>
+declare function $computed<T>(getter: () => T): StxRef<T>
+declare function $watch<T>(
+  source: (() => T) | StxRef<T> | StxSignal<T>,
+  callback: (value: T, oldValue: T) => void,
+  options?: { immediate?: boolean, deep?: boolean },
+): StxCleanup
+
+// ============================================================================
+// Stores (Pinia-inspired, signals-based)
+// ============================================================================
+
+interface StxStorePersistOptions {
+  pick?: string[]
+  storage?: 'localStorage' | 'sessionStorage'
+  key?: string
+}
+
+interface StxStoreOptions {
+  persist?: boolean | StxStorePersistOptions
+}
+
+declare function defineStore<T>(
+  id: string,
+  setup: () => T,
+  options?: StxStoreOptions,
+): () => T
+declare function defineStore<S extends Record<string, any>, G extends Record<string, any>, A extends Record<string, any>>(
+  id: string,
+  options: {
+    state?: () => S
+    getters?: G
+    actions?: A
+    persist?: boolean | StxStorePersistOptions
+  },
+): () => S & G & A
+declare function useStore<T = any>(id: string): T
+declare function createStore<T>(setup: () => T, options?: StxStoreOptions): () => T
+declare function action<T extends (...args: any[]) => any>(fn: T): T
+declare function createSelector<T, R>(selector: (state: T) => R): (state: T) => R
+
+// ============================================================================
+// JSX runtime (Vue/React style)
+// ============================================================================
+
+declare function h(tag: string | Function, props?: Record<string, any> | null, ...children: any[]): any
+declare const Fragment: unique symbol
+
+// ============================================================================
+// window.stx registry
+// ============================================================================
+
+interface StxRuntimeRegistry {
+  // Signals
+  state: typeof state
+  derived: typeof derived
+  effect: typeof effect
+  batch: typeof batch
+  untrack: typeof untrack
+  peek: typeof peek
+  isSignal: typeof isSignal
+
+  // Lifecycle
+  onMount: typeof onMount
+  onDestroy: typeof onDestroy
+
+  // Composables
+  useFetch: typeof useFetch
+  useRef: typeof useRef
+  useQuery: typeof useQuery
+  useMutation: typeof useMutation
+
+  // Routing
+  navigate: typeof navigate
+  goBack: typeof goBack
+  goForward: typeof goForward
+  useRoute: typeof useRoute
+  setRouteParams: typeof setRouteParams
+  useSearchParams: typeof useSearchParams
+
+  // Composition
+  provide: typeof provide
+  defineProps: typeof defineProps
+  withDefaults: typeof withDefaults
+  defineEmits: typeof defineEmits
+  defineExpose: typeof defineExpose
+
+  // Vue compat
+  ref: typeof ref
+  reactive: typeof reactive
+  computed: typeof computed
+  watch: typeof watch
+  watchEffect: typeof watchEffect
+  $computed: typeof $computed
+  $watch: typeof $watch
+
+  // Utilities
+  useDebounce: typeof useDebounce
+  useDebouncedValue: typeof useDebouncedValue
+  useThrottle: typeof useThrottle
+  useInterval: typeof useInterval
+  useTimeout: typeof useTimeout
+  useToggle: typeof useToggle
+  useCounter: typeof useCounter
+  useClickOutside: typeof useClickOutside
+  useFocus: typeof useFocus
+  useAsync: typeof useAsync
+  useLocalStorage: typeof useLocalStorage
+  useEventListener: typeof useEventListener
+  useWebSocket: typeof useWebSocket
+  useColorMode: typeof useColorMode
+  useDark: typeof useDark
+  useHead: typeof useHead
+  useSeoMeta: typeof useSeoMeta
+
+  // Stores
+  defineStore: typeof defineStore
+  useStore: typeof useStore
+
+  // Mount API
+  mount: (setupFn: () => any) => void
+  mountEl: (selector: string, setupFn: () => any) => void
+
+  // Helpers (template helpers — populated by app)
+  helpers: Record<string, any>
+
+  // Internals (escape hatch)
+  [key: string]: any
+}
+
+// Bare global so existing code that references `stx` (without `window.`) still works
+declare const stx: StxRuntimeRegistry
+
+// Augment Window so `window.stx` is typed
+interface Window {
+  stx: StxRuntimeRegistry
+  __STX_STORES__?: Record<string, any>
+  __STX_CURRENT_PROPS__?: Record<string, any>
+  __STX_CURRENT_ELEMENT__?: HTMLElement | null
+  __stxRouter?: boolean
+  __stxRouterConfig?: Record<string, any>
+}