@ismaelsoilet/synapsejs 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ismaelsoilet/synapsejs",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Bun-only fullstack framework where a feature is a single contiguous file",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/client/hooks.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { Result } from '../core/machine-types';
+import { useSynapseContext } from './context';
 
 export interface UseSubscriptionOptions {
   enabled?: boolean;
@@ -86,17 +87,33 @@ export interface UseActionResult<TPayload, TData, TError> {
   reset: () => void;
 }
 
+export interface UseActionOptions<TData, TError> {
+  onSuccess?: (data: TData) => void;
+  onError?: (error: TError) => void;
+}
+
 /**
  * Hook for executing server actions from client UI with reactive state management.
+ * If actionFn is not provided, it automatically resolves the slice's action from SynapseContext.
  */
 export function useAction<TPayload = unknown, TData = unknown, TError = string>(
-  actionFn?: (payload: TPayload) => Promise<Result<TData, TError>>
+  actionFn?: ((payload: TPayload) => Promise<Result<TData, TError>>) | null,
+  options?: UseActionOptions<TData, TError>
 ): UseActionResult<TPayload, TData, TError> {
   const [isSubmitting, setIsSubmitting] = useState<boolean>(false);
   const [data, setData] = useState<TData | null>(null);
   const [error, setError] = useState<TError | null>(null);
   const [isSuccess, setIsSuccess] = useState<boolean>(false);
 
+  const ctx = useSynapseContext();
+  const resolvedAction =
+    actionFn ??
+    (ctx.props?.action as ((payload: TPayload) => Promise<Result<TData, TError>>) | undefined) ??
+    (ctx.props?.onSubmitAction as ((payload: TPayload) => Promise<Result<TData, TError>>) | undefined);
+
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
   const reset = useCallback(() => {
     setIsSubmitting(false);
     setData(null);
@@ -106,9 +123,10 @@ export function useAction<TPayload = unknown, TData = unknown, TError = string>(
 
   const execute = useCallback(
     async (payload: TPayload): Promise<Result<TData, TError>> => {
-      if (!actionFn) {
+      if (!resolvedAction) {
         const errVal = 'NO_ACTION_FUNCTION' as unknown as TError;
         setError(errVal);
+        optionsRef.current?.onError?.(errVal);
         return { ok: false, error: errVal };
       }
 
@@ -117,26 +135,29 @@ export function useAction<TPayload = unknown, TData = unknown, TError = string>(
       setIsSuccess(false);
 
       try {
-        const result = await actionFn(payload);
+        const result = await resolvedAction(payload);
         if (result.ok) {
           setData(result.value);
           setIsSuccess(true);
           setError(null);
+          optionsRef.current?.onSuccess?.(result.value);
         } else {
           setError(result.error);
           setIsSuccess(false);
+          optionsRef.current?.onError?.(result.error);
         }
         return result;
       } catch (err: unknown) {
         const failure = (err instanceof Error ? err.message : String(err)) as unknown as TError;
         setError(failure);
         setIsSuccess(false);
+        optionsRef.current?.onError?.(failure);
         return { ok: false, error: failure };
       } finally {
         setIsSubmitting(false);
       }
     },
-    [actionFn]
+    [resolvedAction]
   );
 
   return {

package/src/client.ts

@@ -41,6 +41,7 @@ export {
 } from './client/context';
 // Reactive Action & Realtime Subscription Hooks
 export {
+  type UseActionOptions,
   type UseActionResult,
   type UseSubscriptionOptions,
   type UseSubscriptionResult,

package/src/compiler/client-bundler.ts

@@ -71,13 +71,77 @@ export async function buildVendorBundle(baseDir: string): Promise<Result<BuiltBu
     `import * as ReactDOM from 'react-dom';`,
     `import * as ReactDOMClient from 'react-dom/client';`,
     `import * as SynapseClient from 'synapsejs/client';`,
+    `import * as jsxRuntime from 'react/jsx-runtime';`,
+    `import * as jsxDevRuntime from 'react/jsx-dev-runtime';`,
     ``,
     `export default React;`,
     `export * from 'react';`,
     `export * from 'react-dom';`,
     `export * from 'react-dom/client';`,
     `export * from 'synapsejs/client';`,
-    `export { ReactDOM, ReactDOMClient, SynapseClient };`,
+    `export * from 'react/jsx-runtime';`,
+    `export * from 'react/jsx-dev-runtime';`,
+    `const { hydrateRoot, createRoot } = ReactDOMClient;`,
+    `const { jsx, jsxs } = (jsxRuntime as unknown as Record<string, unknown>);`,
+    `const { jsxDEV } = (jsxDevRuntime as unknown as Record<string, unknown>);`,
+    `const {`,
+    `  useState,`,
+    `  useEffect,`,
+    `  useCallback,`,
+    `  useMemo,`,
+    `  useRef,`,
+    `  useContext,`,
+    `  useReducer,`,
+    `  useId,`,
+    `  useLayoutEffect,`,
+    `  useTransition,`,
+    `  useDeferredValue,`,
+    `  createContext,`,
+    `  createElement,`,
+    `  cloneElement,`,
+    `  isValidElement,`,
+    `  Fragment,`,
+    `  Component,`,
+    `  PureComponent,`,
+    `  memo,`,
+    `  forwardRef,`,
+    `  Children,`,
+    `  startTransition`,
+    `} = (React as unknown as Record<string, unknown>);`,
+    `export {`,
+    `  ReactDOM,`,
+    `  ReactDOMClient,`,
+    `  SynapseClient,`,
+    `  jsxRuntime,`,
+    `  jsxDevRuntime,`,
+    `  hydrateRoot,`,
+    `  createRoot,`,
+    `  jsx,`,
+    `  jsxs,`,
+    `  jsxDEV,`,
+    `  useState,`,
+    `  useEffect,`,
+    `  useCallback,`,
+    `  useMemo,`,
+    `  useRef,`,
+    `  useContext,`,
+    `  useReducer,`,
+    `  useId,`,
+    `  useLayoutEffect,`,
+    `  useTransition,`,
+    `  useDeferredValue,`,
+    `  createContext,`,
+    `  createElement,`,
+    `  cloneElement,`,
+    `  isValidElement,`,
+    `  Fragment,`,
+    `  Component,`,
+    `  PureComponent,`,
+    `  memo,`,
+    `  forwardRef,`,
+    `  Children,`,
+    `  startTransition`,
+    `};`,
     ``
   ].join('\n');
 
@@ -194,12 +258,51 @@ export async function buildClientBundle(
   const entryPath = path.join(entryDir, `${target.domain}-${target.name}.tsx`);
   const modulePath = path.relative(entryDir, path.join(outDir, clientArtifact.fileName)).split(path.sep).join('/');
 
+  // Detect optional root and domain layouts for isomorphic hydration
+  let rootLayoutPath: string | undefined;
+  let domainLayoutPath: string | undefined;
+
+  let currentDir = path.dirname(target.filePath);
+  let slicesDir: string | null = null;
+  while (currentDir && currentDir !== baseDir && currentDir !== path.dirname(currentDir)) {
+    if (path.basename(currentDir) === 'slices') {
+      slicesDir = currentDir;
+      break;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  if (slicesDir) {
+    const rootCandidates = [path.join(slicesDir, '_layout.tsx'), path.join(slicesDir, 'layout.tsx')];
+    for (const cand of rootCandidates) {
+      if (fs.existsSync(cand)) {
+        const rel = path.relative(entryDir, cand).split(path.sep).join('/');
+        rootLayoutPath = rel.startsWith('.') ? rel : `./${rel}`;
+        break;
+      }
+    }
+
+    const domainDir = path.dirname(target.filePath);
+    if (domainDir !== slicesDir) {
+      const domainCandidates = [path.join(domainDir, '_layout.tsx'), path.join(domainDir, 'layout.tsx')];
+      for (const cand of domainCandidates) {
+        if (fs.existsSync(cand)) {
+          const rel = path.relative(entryDir, cand).split(path.sep).join('/');
+          domainLayoutPath = rel.startsWith('.') ? rel : `./${rel}`;
+          break;
+        }
+      }
+    }
+  }
+
   fs.writeFileSync(
     entryPath,
     clientEntrySource({
       componentName: componentExport,
       clientModulePath: `./${modulePath}`,
-      rpcPath: target.rpcPath
+      rpcPath: target.rpcPath,
+      rootLayoutPath,
+      domainLayoutPath
     }),
     'utf-8'
   );
@@ -224,7 +327,15 @@ export async function buildClientBundle(
       naming: '[name].js',
       minify: production,
       external: vendorSplit
-        ? ['react', 'react-dom', 'react-dom/client', 'synapsejs/client', '@ismaelsoilet/synapsejs/client']
+        ? [
+            'react',
+            'react/jsx-runtime',
+            'react/jsx-dev-runtime',
+            'react-dom',
+            'react-dom/client',
+            'synapsejs/client',
+            '@ismaelsoilet/synapsejs/client'
+          ]
         : [],
       define: { 'process.env.NODE_ENV': production ? '"production"' : '"development"' }
     });

package/src/compiler/scaffolder.ts

@@ -61,7 +61,7 @@ import {
 // ============================================================================
 export const ${inputSchemaName} = Type.Object({
 ${tbProps}
-});
+}, { additionalProperties: true });
 export type ${inputTypeName} = Static<typeof ${inputSchemaName}>;
 
 // DDL Schema Declarativo da Fatia (Auto-Migrado pelo Synapse)
@@ -211,7 +211,7 @@ export const ${inputSchemaName} = Type.Object({
   name: Type.String({ minLength: 2, maxLength: 100 }),
   email: Type.String({ format: 'email' }),
   metadata: Type.Optional(Type.String())
-});
+}, { additionalProperties: true });
 export type ${inputTypeName} = Static<typeof ${inputSchemaName}>;
 
 // DDL Schema Declarativo da Fatia (Auto-Migrado pelo Synapse)

package/src/compiler/schema-dag.ts

@@ -25,26 +25,30 @@ export function parseTableDependencies(ddl: string): { created: string[]; refere
   const created: string[] = [];
   const referenced: string[] = [];
 
-  // Match CREATE TABLE [IF NOT EXISTS] <name>
-  const createRegex = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["'`]?([a-zA-Z0-9_]+)["'`]?/gi;
-  let match: RegExpExecArray | null = createRegex.exec(ddl);
+  // Strip SQL comments to avoid false-positive dependencies
+  const cleanDdl = ddl.replace(/--.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+
+  // Match CREATE TABLE [IF NOT EXISTS] [schema.]<name>
+  const createRegex =
+    /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:["'`]?[a-zA-Z0-9_]+["'`]?\.)?["'`]?([a-zA-Z0-9_]+)["'`]?/gi;
+  let match: RegExpExecArray | null = createRegex.exec(cleanDdl);
   while (match !== null) {
     const tableName = match[1].toLowerCase();
     if (!created.includes(tableName)) {
       created.push(tableName);
     }
-    match = createRegex.exec(ddl);
+    match = createRegex.exec(cleanDdl);
   }
 
-  // Match REFERENCES <name>
-  const refRegex = /REFERENCES\s+["'`]?([a-zA-Z0-9_]+)["'`]?/gi;
-  let refMatch: RegExpExecArray | null = refRegex.exec(ddl);
+  // Match REFERENCES [schema.]<name>[(columns)]
+  const refRegex = /REFERENCES\s+(?:["'`]?[a-zA-Z0-9_]+["'`]?\.)?["'`]?([a-zA-Z0-9_]+)["'`]?/gi;
+  let refMatch: RegExpExecArray | null = refRegex.exec(cleanDdl);
   while (refMatch !== null) {
     const tableName = refMatch[1].toLowerCase();
     if (!created.includes(tableName) && !referenced.includes(tableName)) {
       referenced.push(tableName);
     }
-    refMatch = refRegex.exec(ddl);
+    refMatch = refRegex.exec(cleanDdl);
   }
 
   return { created, referenced };

package/src/compiler/slice-splitter.ts

@@ -75,11 +75,19 @@ const SERVER_ONLY_PATTERNS: Array<{ label: string; pattern: RegExp }> = [
   { label: 'UPDATE statement', pattern: /\bUPDATE\s+\w+\s+SET\b/i },
   { label: 'DELETE statement', pattern: /\bDELETE\s+FROM\b/i },
   { label: 'CREATE TABLE statement', pattern: /\bCREATE\s+TABLE\b/i },
+  { label: 'ALTER TABLE statement', pattern: /\bALTER\s+TABLE\b/i },
+  { label: 'DROP TABLE statement', pattern: /\bDROP\s+TABLE\b/i },
   { label: 'database call', pattern: /\bdb\s*\.\s*(?:query|findMany|findOne|insert|update|delete|sql|sqlOne)\b/ },
   { label: 'sliceSchema symbol', pattern: /\bsliceSchema\b/ },
   { label: 'test runner import', pattern: /from\s+['"]bun:test['"]/ },
-  { label: 'process.env access', pattern: /\bprocess\.env\b/ },
-  { label: 'Bun global', pattern: /\bBun\./ }
+  { label: 'process.env access', pattern: /\bprocess\s*(?:\.\s*env|\[\s*['"]env['"]\s*\])/ },
+  { label: 'process destructuring', pattern: /\b(?:const|let|var)\s*\{[^}]*\benv\b[^}]*\}\s*=\s*process\b/ },
+  { label: 'Bun global', pattern: /\bBun\./ },
+  {
+    label: 'node server module import',
+    pattern: /from\s+['"](?:node:)?(?:fs|child_process|cluster|dgram|dns|net|tls|v8|vm)['"]/
+  },
+  { label: 'dynamic code evaluation', pattern: /\b(?:eval|new\s+Function)\s*\(/ }
 ];
 
 interface DeclEntry {

package/src/compiler/slice-templates.ts

@@ -88,7 +88,7 @@ export const ${names.schemaName} = Type.Object({
   query: Type.Optional(Type.String({ maxLength: 60 })),
   limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
   offset: Type.Optional(Type.Integer({ minimum: 0 }))
-});
+}, { additionalProperties: true });
 export type ${names.inputName} = Static<typeof ${names.schemaName}>;
 
 // ============================================================================
@@ -236,7 +236,7 @@ export const ${names.schemaName} = Type.Object({
   query: Type.Optional(Type.String({ maxLength: 60 })),
   limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
   offset: Type.Optional(Type.Integer({ minimum: 0 }))
-});
+}, { additionalProperties: true });
 export type ${names.inputName} = Static<typeof ${names.schemaName}>;
 
 // A tabela pertence a outra fatia desta mesma feature.
@@ -450,7 +450,7 @@ function updateTemplate(names: TemplateNames): string {
 export const ${names.schemaName} = Type.Object({
   id: Type.String({ minLength: 1 }),
   name: Type.Optional(Type.String({ minLength: 2, maxLength: 120 }))
-});
+}, { additionalProperties: true });
 export type ${names.inputName} = Static<typeof ${names.schemaName}>;
 
 // ============================================================================
@@ -657,7 +657,7 @@ function deleteTemplate(names: TemplateNames): string {
 // ============================================================================
 export const ${names.schemaName} = Type.Object({
   id: Type.String({ minLength: 1 })
-});
+}, { additionalProperties: true });
 export type ${names.inputName} = Static<typeof ${names.schemaName}>;
 
 // ============================================================================
@@ -806,7 +806,7 @@ import { storeSession } from 'synapsejs/client';
 export const ${names.schemaName} = Type.Object({
   email: Type.String({ minLength: 3, maxLength: 200 }),
   password: Type.String({ minLength: 8, maxLength: 200 })
-});
+}, { additionalProperties: true });
 export type ${names.inputName} = Static<typeof ${names.schemaName}>;
 
 // ============================================================================
@@ -1075,7 +1075,7 @@ import {
 export const ${names.schemaName} = Type.Object({
   code: Type.String({ minLength: 1, maxLength: 500 }),
   state: Type.Optional(Type.String({ maxLength: 500 }))
-});
+}, { additionalProperties: true });
 export type ${names.inputName} = Static<typeof ${names.schemaName}>;
 
 // ============================================================================
@@ -1353,7 +1353,7 @@ import { signSessionToken } from 'synapsejs';
 export const ${names.schemaName} = Type.Object({
   userId: Type.String({ minLength: 1 }),
   code: Type.String({ minLength: 6, maxLength: 6 })
-});
+}, { additionalProperties: true });
 export type ${names.inputName} = Static<typeof ${names.schemaName}>;
 
 // ============================================================================

package/src/core/action-definition.ts

@@ -0,0 +1,89 @@
+/**
+ * SynapseJS - Declarative Action Definition Primitive
+ *
+ * Implements "Secure by Default" (Fail-Closed) semantics and wire-speed automatic
+ * TypeBox schema validation. Prevents inadvertent public exposure of RPC endpoints
+ * and eliminates repetitive manual `Value.Check` and `requireAuth` boilerplate.
+ */
+
+import type { Static, TSchema } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import type { DatabaseClient } from './database-client';
+import { Err, type Result } from './machine-types';
+import { requireAuth, type SessionContext } from './session-context';
+
+export type ActionAuthRule = 'public' | string[];
+
+export interface ActionDefinitionConfig<TSchemaInput extends TSchema | undefined, TOutput> {
+  /**
+   * Optional TypeBox schema for input payload validation.
+   * If supplied, incoming requests are automatically validated before the handler runs.
+   */
+  input?: TSchemaInput;
+
+  /**
+   * Authorization rules for this action.
+   * - Omitted / undefined: Requires an authenticated user session (Fail-Closed by default).
+   * - Array of strings (e.g. ['admin', 'manager']): Requires the session to possess at least one of these roles.
+   * - 'public': Explicitly marks the action as accessible to unauthenticated callers.
+   */
+  auth?: ActionAuthRule;
+
+  /**
+   * Handler function executing business logic.
+   * Receives strongly-typed validated input, database client and authenticated session context.
+   */
+  handler: (ctx: {
+    input: TSchemaInput extends TSchema ? Static<TSchemaInput> : unknown;
+    db?: DatabaseClient;
+    session?: SessionContext;
+  }) => Promise<TOutput> | TOutput;
+}
+
+export type ActionHandlerFn<TSchemaInput extends TSchema | undefined, TOutput> = {
+  (
+    payload: unknown,
+    db?: DatabaseClient,
+    session?: SessionContext
+  ): Promise<TOutput | Result<never, 'INVALID_SCHEMA' | 'UNAUTHORIZED' | 'FORBIDDEN'>>;
+  readonly __isSynapseAction: true;
+  readonly config: ActionDefinitionConfig<TSchemaInput, TOutput>;
+};
+
+export function defineAction<TSchemaInput extends TSchema | undefined, TOutput>(
+  config: ActionDefinitionConfig<TSchemaInput, TOutput>
+): ActionHandlerFn<TSchemaInput, TOutput> {
+  const actionFn = async (
+    payload: unknown,
+    db?: DatabaseClient,
+    session?: SessionContext
+  ): Promise<TOutput | Result<never, 'INVALID_SCHEMA' | 'UNAUTHORIZED' | 'FORBIDDEN'>> => {
+    // 1. Fail-Closed Authentication Guard
+    if (config.auth !== 'public') {
+      const requiredRoles = Array.isArray(config.auth) ? config.auth : undefined;
+      const auth = requireAuth(session, requiredRoles);
+      if (!auth.ok) {
+        return Err(auth.error);
+      }
+    }
+
+    // 2. Automatic Wire-Speed Schema Validation
+    if (config.input) {
+      if (!Value.Check(config.input, payload)) {
+        return Err('INVALID_SCHEMA');
+      }
+    }
+
+    // 3. Typed Handler Invocation
+    return config.handler({
+      input: payload as TSchemaInput extends TSchema ? Static<TSchemaInput> : unknown,
+      db,
+      session
+    });
+  };
+
+  Object.defineProperty(actionFn, '__isSynapseAction', { value: true, writable: false });
+  Object.defineProperty(actionFn, 'config', { value: config, writable: false });
+
+  return actionFn as ActionHandlerFn<TSchemaInput, TOutput>;
+}

package/src/core/index.ts

@@ -1,4 +1,5 @@
 export * from './action-context';
+export * from './action-definition';
 export * from './config';
 export * from './database-client';
 export * from './database-factory';
@@ -12,3 +13,4 @@ export * from './session-context';
 export * from './session-token';
 export * from './sqlite-client';
 export * from './storage';
+export * from './validation';

package/src/core/validation.ts

@@ -0,0 +1,57 @@
+/**
+ * SynapseJS - Schema Validation Utilities
+ *
+ * Provides structured, human-readable validation for TypeBox contracts.
+ * Rather than returning an opaque 'INVALID_SCHEMA', it extracts the exact
+ * paths and failure reasons to provide actionable machine and developer diagnostics.
+ */
+
+import type { Static, TSchema } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { Err, Ok, type Result } from './machine-types';
+
+export interface ValidationErrorDetail {
+  path: string;
+  message: string;
+  value?: unknown;
+}
+
+export interface ValidationFailure {
+  code: 'INVALID_SCHEMA';
+  message: string;
+  errors: ValidationErrorDetail[];
+}
+
+/**
+ * Validates a payload against a TypeBox schema with detailed error reporting.
+ * Returns Ok(validatedValue) or Err with formatted diagnosis.
+ */
+export function validateSchema<T extends TSchema>(schema: T, payload: unknown): Result<Static<T>, string> {
+  if (Value.Check(schema, payload)) {
+    return Ok(payload as Static<T>);
+  }
+
+  const errors: ValidationErrorDetail[] = [];
+  try {
+    for (const err of Value.Errors(schema, payload)) {
+      errors.push({
+        path: err.path || '/',
+        message: err.message,
+        value: err.value
+      });
+    }
+  } catch {
+    // Se a extração de erros falhar, mantém fallback seguro
+  }
+
+  if (errors.length === 0) {
+    return Err('INVALID_SCHEMA: Falha na validação do contrato de entrada.');
+  }
+
+  const formattedDetails = errors
+    .slice(0, 3)
+    .map((e) => `campo "${e.path}": ${e.message}`)
+    .join('; ');
+
+  return Err(`INVALID_SCHEMA: ${formattedDetails}`);
+}

package/src/runtime/client-entry.ts

@@ -17,6 +17,8 @@ export interface ClientEntryOptions {
   rpcPath: string;
   rootId?: string;
   actionPropNames?: string[];
+  rootLayoutPath?: string;
+  domainLayoutPath?: string;
 }
 
 export const CLIENT_ROOT_ID = 'synapse-root';
@@ -26,14 +28,25 @@ export function clientEntrySource(options: ClientEntryOptions): string {
   const rootId = options.rootId ?? CLIENT_ROOT_ID;
   const propNames = options.actionPropNames ?? ['onSubmitAction', 'action'];
   const actionWires = propNames
-    .map((name) => `      ${name}: (payload: unknown) => rpcCall(${JSON.stringify(options.rpcPath)}, payload)`)
+    .map((name) => `        ${name}: (payload: unknown) => rpcCall(${JSON.stringify(options.rpcPath)}, payload)`)
     .join(',\n');
 
-  return [
+  const layoutImports: string[] = [];
+  if (options.rootLayoutPath) {
+    layoutImports.push(`import * as RootLayoutModule from ${JSON.stringify(options.rootLayoutPath)};`);
+  }
+  if (options.domainLayoutPath) {
+    layoutImports.push(`import * as DomainLayoutModule from ${JSON.stringify(options.domainLayoutPath)};`);
+  }
+
+  const hasLayouts = Boolean(options.rootLayoutPath || options.domainLayoutPath);
+
+  const lines = [
     `// [SYNAPSE-JS GENERATED CLIENT ENTRY] hydrates the slice in the browser`,
     `import React from 'react';`,
     `import { hydrateRoot } from 'react-dom/client';`,
-    `import { rpcCall } from 'synapsejs/client';`,
+    `import { rpcCall, SynapseProvider } from 'synapsejs/client';`,
+    ...layoutImports,
     `import { ${options.componentName} } from ${JSON.stringify(options.clientModulePath)};`,
     ``,
     `export function hydrate() {`,
@@ -41,19 +54,49 @@ export function clientEntrySource(options: ClientEntryOptions): string {
     `  const props = (scope[${JSON.stringify(CLIENT_PROPS_GLOBAL)}] ?? {}) as Record<string, unknown>;`,
     `  const root = document.getElementById(${JSON.stringify(rootId)});`,
     `  if (root) {`,
-    `    hydrateRoot(`,
-    `      root,`,
-    `      React.createElement(${options.componentName}, {`,
-    `        ...props,`,
+    `    const sliceElement = React.createElement(${options.componentName}, {`,
+    `      ...props,`,
     `${actionWires}`,
-    `      })`,
-    `    );`,
-    `  }`,
-    `}`,
-    ``,
-    `hydrate();`,
-    ``
-  ].join('\n');
+    `    });`
+  ];
+
+  if (hasLayouts) {
+    if (options.domainLayoutPath) {
+      lines.push(
+        `    const DomainLayout = (DomainLayoutModule as any).default || (DomainLayoutModule as any).Layout || null;`
+      );
+    }
+    if (options.rootLayoutPath) {
+      lines.push(
+        `    const RootLayout = (RootLayoutModule as any).default || (RootLayoutModule as any).Layout || null;`
+      );
+    }
+    let treeExpr = 'sliceElement';
+    if (options.domainLayoutPath) {
+      treeExpr = `(typeof DomainLayout === 'function' ? React.createElement(DomainLayout, { ...props }, ${treeExpr}) : ${treeExpr})`;
+    }
+    if (options.rootLayoutPath) {
+      treeExpr = `(typeof RootLayout === 'function' ? React.createElement(RootLayout, { ...props }, ${treeExpr}) : ${treeExpr})`;
+    }
+    lines.push(`    const treeWithLayout = ${treeExpr};`);
+    lines.push(`    hydrateRoot(`);
+    lines.push(`      root,`);
+    lines.push(`      React.createElement(SynapseProvider, { props, session: props.session as any }, treeWithLayout)`);
+    lines.push(`    );`);
+  } else {
+    lines.push(`    hydrateRoot(`);
+    lines.push(`      root,`);
+    lines.push(`      React.createElement(SynapseProvider, { props, session: props.session as any }, sliceElement)`);
+    lines.push(`    );`);
+  }
+
+  lines.push(`  }`);
+  lines.push(`}`);
+  lines.push(``);
+  lines.push(`hydrate();`);
+  lines.push(``);
+
+  return lines.join('\n');
 }
 
 /**

package/src/runtime/server.ts

@@ -356,7 +356,8 @@ export class SynapseServer {
     for (const cand of layoutCandidates) {
       if (fs.existsSync(cand)) {
         try {
-          const layoutMod = await import(cand);
+          const candStat = fs.statSync(cand);
+          const layoutMod = await import(`${cand}?t=${candStat.mtimeMs}`);
           this.layoutComponent = layoutMod.default || layoutMod.Layout || null;
           break;
         } catch (e) {
@@ -380,7 +381,8 @@ export class SynapseServer {
         for (const cand of domainCandidates) {
           if (fs.existsSync(cand)) {
             try {
-              const domainMod = await import(cand);
+              const candStat = fs.statSync(cand);
+              const domainMod = await import(`${cand}?t=${candStat.mtimeMs}`);
               const domainComp = domainMod.default || domainMod.Layout || null;
               if (domainComp) {
                 this.domainLayouts.set(domain, domainComp);
@@ -399,7 +401,8 @@ export class SynapseServer {
       }
 
       try {
-        const mod = await import(file);
+        const fileStat = fs.existsSync(file) ? fs.statSync(file) : null;
+        const mod = await import(fileStat ? `${file}?t=${fileStat.mtimeMs}` : file);
         let actionFn: any = null;
         let componentFn: any = null;
         let componentExport: string | undefined;
@@ -624,10 +627,12 @@ export class SynapseServer {
       return null;
     }
 
-    const signature = String(fs.statSync(slice.filePath).mtimeMs);
+    const stat = fs.existsSync(slice.filePath) ? fs.statSync(slice.filePath) : null;
+    const signature = stat ? String(stat.mtimeMs) : 'missing';
     const cached = this.clientBundles.get(slice.key);
     if (cached?.builtFor === signature) {
-      return cached.url;
+      const version = stat ? `?v=${Math.floor(stat.mtimeMs)}` : '';
+      return `${cached.url}${version}`;
     }
 
     // `synapse build` já empacotou esta fatia e o arquivo não mudou desde então:
@@ -639,7 +644,8 @@ export class SynapseServer {
     const prebuilt = freshBundleFrom(this.clientManifest, slice.key, Number(signature));
     if (prebuilt) {
       this.clientBundles.set(slice.key, { url: prebuilt, builtFor: signature });
-      return prebuilt;
+      const version = stat ? `?v=${Math.floor(stat.mtimeMs)}` : '';
+      return `${prebuilt}${version}`;
     }
 
     const built = await buildClientBundle(
@@ -660,7 +666,8 @@ export class SynapseServer {
 
     this.clientBundles.set(slice.key, { url: built.value.url, builtFor: signature });
 
-    return built.value.url;
+    const version = stat ? `?v=${Math.floor(stat.mtimeMs)}` : '';
+    return `${built.value.url}${version}`;
   }
 
   /**
@@ -696,7 +703,8 @@ export class SynapseServer {
     propsJson: string,
     clientUrl: string | null,
     meta?: SliceMetadata,
-    locale = 'pt-BR'
+    locale = 'pt-BR',
+    hasLayout = false
   ): string {
     const safeTitle = escapeHtml(title);
     const safeSliceName = escapeHtml(sliceName);
@@ -729,6 +737,44 @@ export class SynapseServer {
     }
     const metaSection = metaTags.length > 0 ? `\n${metaTags.join('\n')}` : '';
 
+    if (hasLayout) {
+      return `<!DOCTYPE html>
+<html lang="${escapeHtml(locale)}" class="min-h-full">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${pageTitle}</title>${metaSection}
+${this.renderStylesheets()}
+  <script type="importmap">
+  {
+    "imports": {
+      "react": "/_synapse/client/_vendor.js",
+      "react/jsx-runtime": "/_synapse/client/_vendor.js",
+      "react/jsx-dev-runtime": "/_synapse/client/_vendor.js",
+      "react-dom": "/_synapse/client/_vendor.js",
+      "react-dom/client": "/_synapse/client/_vendor.js",
+      "synapsejs/client": "/_synapse/client/_vendor.js",
+      "@ismaelsoilet/synapsejs/client": "/_synapse/client/_vendor.js"
+    }
+  }
+  </script>
+  <script type="module" src="/_synapse/client/_vendor.js"></script>
+  <style>
+    body { font-family: 'Inter', sans-serif; }
+    code, pre { font-family: 'JetBrains Mono', monospace; }
+  </style>
+</head>
+<body class="min-h-full flex flex-col">
+  <div id="synapse-root" class="min-h-full flex-1 flex flex-col">${contentHtml}</div>
+
+  <script data-synapse-props>globalThis.__SYNAPSE_PROPS__ = ${propsJson};</script>
+  ${clientUrl ? `<script data-synapse-client type="module" src="${clientUrl}"></script>` : '<!-- sem componente hidratavel -->'}
+
+  <script type="module" src="/_synapse/turbo-router.js"></script>
+</body>
+</html>`;
+    }
+
     return `<!DOCTYPE html>
 <html lang="${escapeHtml(locale)}" class="h-full bg-slate-950 text-slate-100">
 <head>
@@ -740,9 +786,12 @@ ${this.renderStylesheets()}
   {
     "imports": {
       "react": "/_synapse/client/_vendor.js",
+      "react/jsx-runtime": "/_synapse/client/_vendor.js",
+      "react/jsx-dev-runtime": "/_synapse/client/_vendor.js",
       "react-dom": "/_synapse/client/_vendor.js",
       "react-dom/client": "/_synapse/client/_vendor.js",
-      "synapsejs/client": "/_synapse/client/_vendor.js"
+      "synapsejs/client": "/_synapse/client/_vendor.js",
+      "@ismaelsoilet/synapsejs/client": "/_synapse/client/_vendor.js"
     }
   }
   </script>
@@ -1501,6 +1550,7 @@ ${this.renderStylesheets()}
 
             this.logRequest(req, pathname, 200, startedAt, session, 'ssr');
 
+            const hasCustomLayout = Boolean(this.layoutComponent || this.domainLayouts.get(slice.domain));
             const html = this.renderHtmlShell(
               meta?.title || slice.name,
               contentHtml,
@@ -1508,7 +1558,8 @@ ${this.renderStylesheets()}
               serializeClientProps(dataProps),
               clientUrl,
               meta,
-              matchedLocale || 'pt-BR'
+              matchedLocale || 'pt-BR',
+              hasCustomLayout
             );
             return new Response(html, {
               headers: { 'Content-Type': 'text/html; charset=utf-8' }